total-agent-memory

# total-agent-memory

<!-- mcp-name: io.github.vbcherepanov/total-agent-memory -->

> **Persistent memory for your facts, decisions and working practices.**
> Persistent, local memory for AI coding agents: Claude Code, Codex CLI, Cursor, any MCP client.
> Temporal knowledge graph · procedural memory · AST codebase ingest · cross-project analogy · 3D WebGL visualization.

[![Version](https://img.shields.io/badge/version-14.0.0-8ad.svg)](https://pypi.org/project/total-agent-memory/)
[![Tests](https://img.shields.io/badge/tests-2162%20passing-4a9.svg)](docs/benchmarks/release-final-v14-20260915/RESULTS.md)
[![IDEs](https://img.shields.io/badge/IDEs-9%20supported-4a9.svg)]()
[![LongMemEval R@5](https://img.shields.io/badge/LongMemEval%20R@5-95.1%25-4a9.svg)](evals/longmemeval-2026-08-27-v13-store.json)
[![LoCoMo R@5](https://img.shields.io/badge/LoCoMo%20R@5-0.607-4a9.svg)](benchmarks/results/v13-locomo-retrieval.json)
[![BEAM R@5](https://img.shields.io/badge/BEAM%201M%20R@5-0.448-4a9.svg)](benchmarks/results/v13-beam-1M.json)
[![Local-First](https://img.shields.io/badge/100%25-local-4a9.svg)]()
[![License](https://img.shields.io/badge/license-MIT-fa4.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2026--07--28-blue.svg)](https://modelcontextprotocol.io)
[![npm](https://img.shields.io/badge/npm-total--agent--memory-cb3837.svg)](https://www.npmjs.com/package/total-agent-memory)
[![PyPI](https://img.shields.io/badge/PyPI-total--agent--memory-3776AB.svg)](https://pypi.org/project/total-agent-memory/)
[![Docker GHCR](https://img.shields.io/badge/docker-ghcr.io-2496ED.svg)](https://github.com/vbcherepanov/total-agent-memory/pkgs/container/total-agent-memory)
[![Homebrew](https://img.shields.io/badge/brew-vbcherepanov%2Ftap-FBB040.svg)](https://github.com/vbcherepanov/homebrew-tap)
[![Donate](https://img.shields.io/badge/PayPal-Donate-00457C.svg?logo=paypal&logoColor=white)](https://PayPal.Me/vbcherepanov)

**Why this, not mem0 / Letta / Zep / Supermemory / Cognee?** → [docs/vs-competitors.md](docs/vs-competitors.md)

---

## Version 14.0.0 — what is new

**Release date: 2026-09-15 · Status: release candidate; registry publication pending.**
Use the prepared wheel or this source checkout for v14. The general package-manager commands below follow their published channels and do not guarantee v14 before publication.

| Change | How you use it |
|---|---|
| **Personal, team and shared memory** | Install one server; give Vasya and Petya separate tokens. Select a scope when saving; search all areas you can access. Each area has its own database, graph and index. |
| **Authorship and revision history** | The token identifies the author and client. See who changed a record, when and why; revision checks prevent overwriting another person's edit. |
| **Remote MCP and team web interface** | Connect an IDE through the lightweight Python bridge. In the browser, select a scope, search, browse, save, edit and inspect history. The interface displays the product name, version and release date. |
| **Lower CPU pressure** | Fast mode remains the default. Embedding and optional PyTorch models default to one compute thread. The team server retains three workspace workers to avoid repeated model loading. |
| **Configurable internal LLMs** | Use Ollama, an OpenAI-compatible endpoint or Anthropic for internal text tasks; explicitly select a vision model for images. |
| **Safer retrieval and answers** | Scoped context, model-aware vector search and privacy-safe write intents. The optional grounded reader checks supporting evidence and rejects contradictory claims; it is not the default answer path. |
| **Installation and packaging fixes** | Wheel, source archive and Docker checks cover Linux, Windows and macOS; the source archive now includes test fixtures and installation support files. |

**Validation:** 2,162 tests passed in the checkout; 2,145 passed from the source archive. Native wheel checks passed on Ubuntu, Windows and macOS; 12 browser scenarios passed across Chromium, Firefox and WebKit. The expanded CI matrix still requires execution. See the [final verification report](docs/benchmarks/release-final-v14-20260915/RESULTS.md) for skips, exact platforms and artifact hashes.

**Performance limits:** BGE is optional. On the measured Linux ARM64 setup, its one-thread p95 was about **2,179 ms**, above the 200 ms target. Limiting threads reduces parallel CPU load; it does not eliminate CPU work. No top-10 ranking or new default answer-quality improvement is claimed. [CPU measurements](docs/benchmarks/grounded-v14/CPU_RESULTS.md).

[Full v14 release notes](docs/RELEASE_V14.md) · [Changelog and previous releases](CHANGELOG.md)

## Getting started with v14

### Choose local or server mode

| Mode | Install and use |
|---|---|
| **Local, one person** | Follow [native or Docker installation](#install), then [Quick start](#quick-start). Memory and models run on your machine; the local MCP catalogue has 74 tools. |
| **Server, multiple people** | Follow the setup below. Memory and models run on the server; clients need only Python and their token. The remote catalogue exposes eight core tools. |

The server instructions work with the prepared v14 wheel on Linux, macOS and Windows. Run commands in a directory where you can create the data folder and token files.

### Start a server without Docker

Install the candidate wheel in a dedicated environment. Linux/macOS:

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install ./dist/total_agent_memory-14.0.0-py3-none-any.whl
```

Windows PowerShell, using the environment directly without changing the execution policy:

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .\dist\total_agent_memory-14.0.0-py3-none-any.whl
$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
```

Then, on any of these systems:

```sh
tam-team --root ./team-data user-add vasya 'Vasya'
tam-team --root ./team-data user-add petya 'Petya'
tam-team --root ./team-data team-add engineering 'Engineering'
tam-team --root ./team-data member vasya engineering editor
tam-team --root ./team-data member petya engineering editor
tam-team --root ./team-data token-create vasya --client codex --out ./vasya.token
tam-team --root ./team-data token-create petya --client cursor --out ./petya.token
tam-team --root ./team-data serve --host 127.0.0.1 --port 3738
```

Open `http://127.0.0.1:3738/` and sign in with the contents of your token file. Keep each token private; give Petya his own token, not Vasya's. For access from other machines, configure an HTTPS reverse proxy to the server's `/mcp/` endpoint and web interface. [Permissions, backup, restore and server configuration](docs/TEAM_SERVER_V14.md).

### Start a server with Docker Compose

From this checkout, with port 3738 available:

```sh
docker compose -f docker-compose.team.yml build
docker compose -f docker-compose.team.yml run --rm team-memory python /app/src/team_memory/cli.py user-add vasya 'Vasya'
docker compose -f docker-compose.team.yml run --rm team-memory python /app/src/team_memory/cli.py token-create vasya --client codex --out /team-data/vasya.token
docker compose -f docker-compose.team.yml up -d
docker compose -f docker-compose.team.yml cp team-memory:/team-data/vasya.token ./vasya.token
```

The web interface is at `http://127.0.0.1:3738/`. The token copied to the host is a credential: restrict file access to its owner. To add Petya, a team and membership, use the same CLI subcommands shown above through `docker compose -f docker-compose.team.yml run --rm team-memory python /app/src/team_memory/cli.py`.

Compose keeps data and model caches in persistent volumes. Set `TAM_TEAM_PORT`, `TAM_TEAM_MAX_WORKERS` and LLM settings in `.env` as needed; see [.env.example](.env.example). Plan at least 4 GiB RAM for three warm MiniLM workers and measure your own workload. [Docker server details](docs/TEAM_SERVER_V14.md#docker).

### Connect a remote IDE

Copy `src/team_memory/remote.py` to the client and supply its personal token file. This bridge uses only the Python standard library. For clients with an `mcpServers` configuration:

```json
{
  "mcpServers": {
    "total-agent-memory": {
      "command": "python3",
      "args": ["/absolute/path/remote.py"],
      "env": {
        "TAM_REMOTE_URL": "https://YOUR_SERVER/mcp/",
        "TAM_REMOTE_TOKEN_FILE": "/absolute/path/vasya.token"
      }
    }
  }
}
```

Replace the paths and server address. On Windows use the path to `python.exe` and Windows file paths. Local testing may use `http://127.0.0.1:3738/mcp/`; remote connections require HTTPS. If the package is installed on the client, `tam-remote` is also available. [Client configuration details](docs/TEAM_SERVER_V14.md#лёгкий-удалённый-клиент).

### Save, search and see who changed what

Ask your agent to call `memory_scopes` first to list available areas. These are example arguments for the remote `memory_save` tool:

```jsonl
{"content":"My investigation notes", "scope":{"kind":"personal"}, "tags":["release-v14"]}
{"content":"Engineering release checklist", "scope":{"kind":"team","team_id":"engineering"}, "tags":["release-v14"]}
{"content":"Company-wide onboarding guide", "scope":{"kind":"shared"}, "tags":["onboarding"]}
```

- **Personal:** visible only to the token's owner; this is the default for saves.
- **Team:** visible to members; `reader` can read, `editor` can also change records.
- **Shared:** readable and editable by every authenticated user of this server.
- **Tags:** organize topics. Access comes from `scope` and membership; reserved `scope:`, `team:` and `user:` tags are managed by the server.

Call `memory_recall` with `{"query":"release checklist"}` to search all accessible areas, or add a `scope` to narrow the search. Use `memory_get` and `memory_history` with the returned record's `id` and `scope` to inspect content, author and changes. `memory_update` requires those fields plus `expected_revision`, `content` and `reason`; us