Total Agent Memory

total-agent-memory

> The only memory layer that learns how you work — not just what you said. > 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.

[](https://pypi.org/project/total-agent-memory/) []() []() [](evals/longmemeval-2026-04-17.json) [](benchmarks/results/) [](docs/vs-competitors.md) [](evals/results-2026-04-17.json) []() [](LICENSE) [](https://modelcontextprotocol.io) [](https://www.npmjs.com/package/total-agent-memory) [](https://pypi.org/project/total-agent-memory/) [](https://github.com/vbcherepanov/total-agent-memory/pkgs/container/total-agent-memory) [](https://github.com/vbcherepanov/homebrew-tap) [](https://PayPal.Me/vbcherepanov)

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

---

v12.2.0 — v11 W3 dispatch fix + Codex env alignment (2026-05-24)

Bugfix release. Four v11 W3 MCP tools — memory_recall_iterative, memory_temporal_query, memory_entity_resolve, memory_consolidate_status — were silently broken on main: the dispatcher forwarded an out-of-scope args symbol, the resulting NameError was swallowed by call_tool's exception handler, and clients saw "Error: name 'args' is not defined". Fix passes the per-call args, with regression coverage via tests/test_v11_dispatch_args.py.

Also aligns the Codex installer env with the .tam memory layout (TAM_MEMORY_DIR canonical, CLAUDE_MEMORY_DIR kept as compatibility alias, MEMORY_MODE=fast default) and isolates install tests from real launchctl / systemctl / XDG directories. Full notes in [CHANGELOG.md](CHANGELOG.md#1220--2026-05-24--v11-w3-dispatch-fix--codex-env-alignment).

---

v12.1.0 — Claude Code v2.1.145 subagent lineage (2026-05-20)

Claude Code v2.1.139+ emits subagent IDs on every API request (x-claude-code-agent-id / x-claude-code-parent-agent-id HTTP headers, plus the same fields as agent_id / parent_agent_id attributes on the claude_code.tool and claude_code.llm_request OTEL spans). v12.1 wires these through end-to-end:

• Schema (migration 028_agent_lineage.sql) — nullable agent_id and

parent_agent_id columns on knowledge, partial indexes (WHERE … IS NOT NULL) so lineage filters are free.

• MCP tools — memory_save and memory_save_fast accept two new

optional inputs: agent_id and parent_agent_id. Old callers see no behaviour change.

• extract_transcript.py — reads agent_id / agentId /

parent_agent_id / parentAgentId from .jsonl when Claude Code writes them, and falls back to isSidechain=true as a proxy: sessions with any sidechain activity get agent_id = "session-" plus a has-subagent-work tag on their auto-extracted rows.

• KG fact spawned_by — when memory_save carries both ids, the

store auto-records TemporalKG.add_fact(agent, "spawned_by", parent, source="agent-lineage", invalidate_previous=False). Idempotent. kg_at(timestamp) and kg_timeline() can now reconstruct the subagent lineage tree at any past moment.

A reconnect of the MCP memory server is required for clients to see the updated inputSchema. Full notes in [CHANGELOG.md](CHANGELOG.md#1210--2026-05-20--claude-code-v21145-subagent-lineage).

---

v12.0.0 — rebrand to total-agent-memory (2026-05-16)

The project was renamed from claude-total-memory to total-agent-memory to reflect that it works with every MCP client, not just Claude Code (Cursor, Codex CLI, Cline, Continue, Aider, Windsurf, Gemini CLI, OpenCode — all covered).

Nothing breaks. The old PyPI package (claude-total-memory==11.3.0) is now a deprecation shim that auto-resolves to total-agent-memory>=12.0.0. Legacy imports, CLI binaries, env vars, and the ~/.claude-memory/ directory keep working through automatic migration:

| Old | New | Backward-compat | |---|---|---| | pip install claude-total-memory | pip install total-agent-memory | old name still works (shim + warning) | | from claude_total_memory import … | from total_agent_memory import … | old import still works (sys.modules alias + warning) | | claude-total-memory CLI | total-agent-memory (alias tam) | old CLI still ships in v12 wheel | | CLAUDE_MEMORY_DIR env | TAM_MEMORY_DIR env | old env still respected (deprecation warning) | | ~/.claude-memory/ dir | ~/.tam/ dir | auto-migrated on first run; ~/.claude-memory becomes a symlink to ~/.tam/ so pinned scripts keep working |

Six install paths — pick one:

npx -y total-agent-memory connect claude-code            # Node, zero-install
uvx total-agent-memory                                    # Python via uv (fast)
pipx install total-agent-memory                           # Python via pipx (isolated)
brew install vbcherepanov/tap/total-memory                # Homebrew (macOS / Linuxbrew)
docker run -p 37737:37737 -v ~/.tam:/data \
  ghcr.io/vbcherepanov/total-agent-memory:12.2.0          # Docker (multi-arch amd64+arm64)
git clone https://github.com/vbcherepanov/total-agent-memory \
  ~/total-agent-memory && cd ~/total-agent-memory && ./install.sh   # manual

The npx path also wires the MCP entry into the IDE you pass to connect : claude-code, codex, cursor, cline, continue, aider, windsurf, gemini-cli, opencode.

Project URLs: totalmemory.dev · PyPI · npm · Docker GHCR · GitHub Release

Full migration notes (Docker volume names kept for backward-compat, brew formula changes, etc.) live in [CHANGELOG.md](CHANGELOG.md). The historical sections below (v11.1, v11.0, …) are preserved for reference.

---

v11.1 — graph dedup + proactive save nudges

Two client-reported bugs fixed (2026-05-14):

Bug #1 — orphan + duplicate graph_nodes. The graph accumulated case-variant duplicates (Vue / vue / VUE) and type-collision duplicates (vue/concept vs vue/technology created by different extractors), plus orphan nodes when an edge insert failed after both nodes were already committed. Fixed by migration 026_graph_nodes_dedup (name_norm column, triggers, indexes), a case-insensitive UPSERT rewrite of add_node with type-collision detection, a new atomic GraphStore.link_pair() helper, and a one-shot cleanup tool src/tools/merge_duplicate_nodes.py (dry-run by default).

# After upgrade migration 026 applies automatically. Then optionally:
.venv/bin/python src/tools/merge_duplicate_nodes.py --dry-run
.venv/bin/python src/tools/merge_duplicate_nodes.py --apply --add-unique

Verified on a real production DB (8304 nodes): 102 duplicates merged, 1472 stale edges cleaned, UNIQUE constraint installed.

Bug #2 — model never calls memory_save on its own. Sonnet/Haiku skip the priority-10 save rule when SessionStart context fades. v11.1 adds in-session nudges: a counter in ~/.claude-memory/state/ tracks writes-vs-saves per session, and hooks/post-tool-use.{sh,ps1} emits a stdout line that Claude reads as system context on the next turn. Soft nudge at 3 edits with 0 saves, hard at 7, and a MEMORY_FINAL_WARNING on session stop. A new priority-10 rule instructs the model to treat MEMORY_NUDGE as an immediate command.

Tunables: MEMORY_NUDGE_DISABLE=1 to silence; MEMORY_NUDGE_SOFT / _HARD / _STEP to retune (defaults 3 / 7 / 3).

Test coverage: +24 graph tests, +12 nudge tests. Full details in [CHANGELOG.md](CHANGELOG.md#1110--2026-05-14--graph-dedup--proactive-save-nudges).

---

v11.0 — production memory engine

v11.0 = production memory engine: fast deterministic memory core + async AI enrichment layer. Default mode is fast: zero LLM, zero Ollama, zero network in the save/search/recall hot path.

The codebase is now split into two layers:

• src/memory_core/* — deterministic facade modules (storage, embeddings, vectorstore, classifier, chunker, dedup, cache, graphlinks, telemetry, health, embedding_spaces). No LLM imports allowed. Enforced by tests/test_no_llm_hot_path.py.
• src/ai_layer/* — every LLM-touching path (enrichmentworker, summarizer, keywordextractor, questiongenerator, relationextractor, contradictiondetector, reflection, selfimprove, plus thin shims for qualitygate / corefresolver / reranker / queryrewriter). Off-limits to memorycore.

Architecture details and full hot-path audit: [docs/v11/audit.md](docs/v11/audit.md).

Modes

MEMORY_MODE selects the runtime profile. Default is fast.

| Mode | Hot-path LLM | Async enrichment | Reranker | Embed fallback | Use when | |---|:-:|:-:|:-:|:-:|---| | ultrafast | off | off | off | FastEmbed only (vector index off, FTS-only) | Throughput stress / CI | | fast (default) | off | off | off | FastEmbed only, Ollama fallback gated | Production coding-agent loop | | balanced | off (sync) | on | off | FastEmbed only | You want LLM-derived facets, but never on the critical path | | deep | on (sync) | on | on (when rerank=true) | FastEmbed → Ollama ladder | v10.5 behaviour: quality gate / contradiction / coref / HyDE inline |

deep mode reproduces v10.5.0 defaults exactly. Set MEMORY_MODE=deep if you depended on synchronous qualitygate, contradictiondetector, or coref. balanced keeps the same ergonomics but moves enrichment off-thread.

Migration from v10.5: [docs/v11/MIGRATION-FROM-V10.md](docs/v11/MIGRATION-FROM-V10.md).

v11.0 hot-path benchmark

Warm, in-memory SQLite, MacBook M-series, MEMORY_MODE=fast, MEMORY_ALLOW_OLLAMA_IN_HOT_PATH=false:

| metric | p50 | p95 | p99 | |---------------------|------:|------:|------:| | save_fast | 6.5 | 9.0 | 27.8 | | save_fast cached | 0.3 | 0.4 | 1.1 | | search_fast | 3.7 | 4.0 | 6.2 | | cached_search | 0.0 | 0.0 | 0.0 |

llm_calls = 0, network_calls = 0 across the entire hot path. Reproduce: bin/memory-bench. CI gate: bin/memory-perf-gate. Raw artifact: [docs/v11/benchmark.md](docs/v11/benchmark.md).

v10.5 → v11.0 — same workload, same script

The v10.5 native bench (benchmarks/v10_5_latency.py) re-run on v11 fast against the recorded v10.5 baseline (benchmarks/results/v10_5_latency.json):

| metric | v10.5 sync (with LLM) | v11.0 fast | speedup | |-----------------------|----------------------:|-----------:|--------:| | save p95 | 2150.51 ms | 8.51 ms | 252× | | save p99 | 2178.98 ms | 11.09 ms | 196× | | recall p95 | 1424.26 ms | 5.81 ms | 245× | | recall p99 | 1771.70 ms | 6.75 ms | 262× | | LLM calls / save | 2-4 | 0 | gate | | Network calls / save | 1-3 | 0 | gate |

Even versus v10.5 without LLM (23.3 ms p95), v11 fast is 2.7× faster — the deterministic-only stages (qualitygate probe, contradiction candidate fetch, episodic event creation, projectwiki refresh) are now fully bypassed in fast mode and queued only when MEMORY_ENRICHMENT_ENABLED=true.

Recall quality is preserved: LongMemEval R@5 = 100% on a 30-question sample; hybrid retrieval (FTS5 + dense + RRF + base graph) is identical to v10.5 except for HyDE / analyze_query LLM expansion which is opt-in via MEMORY_MODE=deep. See [docs/v11/benchmark.md](docs/v11/benchmark.md) for the full table including LoCoMo and per-space embedding load characteristics.

New MCP tools in v11.0

memory_save_fast · memory_search_fast · memory_explain_search · memory_warmup · memory_perf_report · memory_rebuild_fts · memory_rebuild_embeddings · memory_eval_locomo · memory_eval_recall · memory_eval_temporal · memory_eval_entity_consistency · memory_eval_contradictions · memory_eval_long_context

All previous tool names (memory_save, memory_recall, ...) continue to work unchanged.

Multi-embedding-space contract

Every vector row now records embedding_provider / embedding_model / embedding_dimension / embedding_space / content_type / language. Spaces: text / code / log / config. Single Chroma backend; per-space model swap is one env flip:

MEMORY_TEXT_EMBED_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
MEMORY_CODE_EMBED_MODEL=jinaai/jina-embeddings-v2-base-code   # optional
MEMORY_LOG_EMBED_MODEL=                                       # falls back to TEXT
MEMORY_CONFIG_EMBED_MODEL=                                    # falls back to TEXT

Old chunks stay searchable in their space; new chunks pick up the swapped model. Backfill one space at a time via memory_rebuild_embeddings.

> v10.x sections below are preserved as legacy v10.5 behaviour — still available via MEMORY_MODE=deep. The numbers, screenshots, and benchmark blocks dated 2026-04-19 / 2026-04-25 / 2026-04-27 (v10) describe the deep-mode pipeline. v11 replaces defaults, not capabilities.

---

Table of contents

• [v11.1 — graph dedup + proactive save nudges](#v111--graph-dedup--proactive-save-nudges)
• [v11.0 — production memory engine](#v110--production-memory-engine)
• [The problem it solves](#the-problem-it-solves)
• [60-second demo](#60-second-demo)
• [Benchmarks — how it compares](#benchmarks--how-it-compares)
• [Competitor comparison](#competitor-comparison)
• [What you get](#what-you-get)
• [Architecture](#architecture)
• [Install](#install)
• [Quick start](#quick-start)
• [CLI: lookup-memory for sub-agents](#cli-lookup-memory-for-sub-agents)
• [MCP tools reference](#mcp-tools-reference-60-tools)
• [TypeScript SDK](#typescript-sdk)
• [Dashboard](#dashboard-localhost37737)
• [Update](#update)
• [Upgrading from v8.x to v9.0](#upgrading-from-v8x-to-v90)
• [Upgrading from v7.x to v8.0](#upgrading-from-v7x-to-v80)
• [Ollama setup](#ollama-setup-optional-but-recommended)
• [Configuration](#configuration)
• [Performance tuning](#performance-tuning)
• [Roadmap](#roadmap)
• [Support the project](#support-the-project)
• [Philosophy & license](#philosophy)

---

The problem it solves

AI coding agents have amnesia. Every new Claude Code / Codex / Cursor session starts from zero. Yesterday's architectural decisions, bug fixes, stack choices, and hard-won lessons vanish the moment you close the terminal. You re-explain the same things, re-discover the same solutions, paste the same context into every new chat.

total-agent-memory gives the agent a persistent brain — on your machine, not in someone else's cloud.

Every decision, solution, error, fact, file change, and session summary is:

• Captured — explicitly via memory_save or implicitly via hooks on file edits / bash errors / session end
• Linked — automatically extracted into a knowledge graph (entities, relations, temporal facts)
• Searchable — 6-stage hybrid retrieval (BM25 + dense + graph + CrossEncoder + MMR + RRF fusion), 96.2% R@5 on public LongMemEval
• Private — 100% local. SQLite + FastEmbed + optional Ollama. No data leaves your machine.

---

60-second demo

You:     "remember we picked pgvector over ChromaDB because of multi-tenant RLS"
Claude:  ✓ memory_save(type=decision, content="Chose pgvector over ChromaDB",
                       context="WHY: single Postgres, per-tenant RLS")

[3 days later, different session, possibly different project directory:]

You:     "why did we pick pgvector again?"
Claude:  ✓ memory_recall(query="vector database choice")
         → "Chose pgvector over ChromaDB for multi-tenant RLS. Single DB
            instance, row-l

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vbcherepanov](https://github.com/vbcherepanov)
- **Source:** [vbcherepanov/total-agent-memory](https://github.com/vbcherepanov/total-agent-memory)
- **License:** MIT
- **Homepage:** https://totalmemory.dev

Install and usage instructions live in the source repository linked above.