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.

]() ]() ]()

Why this, not mem0 / Letta / Zep / Supermemory / Cognee? → 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.

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-<id>" 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.

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:

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 <ide>: 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. 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.

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, vector_store, classifier, chunker, dedup, cache, graph_links, telemetry, health, embedding_spaces). No LLM imports allowed. Enforced by tests/test_no_llm_hot_path.py`.
• *`src/ai_layer/`** — every LLM-touching path (enrichment_worker, summarizer, keyword_extractor, question_generator, relation_extractor, contradiction_detector, reflection, self_improve, plus thin shims for quality_gate / coref_resolver / reranker / query_rewriter). Off-limits to memory_core.

Architecture details and full hot-path audit: docs/v11/audit.md.

Modes

MEMORY_MODE selects the runtime profile. Default is fast.

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

Migration from v10.5: 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:

`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.

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):

Even versus v10.5 _without_ LLM (23.3 ms p95), v11 fast is 2.7× faster — the deterministic-only stages (quality_gate probe, contradiction candidate fetch, episodic event creation, project_wiki 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 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
• v11.0 — production memory engine
• The problem it solves
• 60-second demo
• Benchmarks — how it compares
• Competitor comparison
• What you get
• Architecture
• Install
• Quick start
• CLI: lookup-memory for sub-agents
• MCP tools reference
• TypeScript SDK
• Dashboard
• Update
• Upgrading from v8.x to v9.0
• Upgrading from v7.x to v8.0
• Ollama setup
• Configuration
• Performance tuning
• Roadmap
• Support the project
• Philosophy & license

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-level security per tenant."

It's not just retrieval. It's procedural too:

You:     "migrate auth middleware to JWT-only session tokens"
Claude:  ✓ workflow_predict(task_description="migrate auth middleware...")
         → confidence 0.82, predicted steps:
             1. read src/auth/middleware.go + tests
             2. update session fixtures in tests/
             3. run migration 0042
             4. regenerate OpenAPI spec
           similar past: wf#118 (success), wf#93 (success)

Benchmarks — how it compares

Public LongMemEval benchmark (xiaowu0162/longmemeval-cleaned, 470 questions, the dataset everyone publishes against):

                   R@5 (recall_any) on public LongMemEval
                   ─────────────────────────────────────────
  100% ─┤
        │
  96.2% ┤  ████  ← total-agent-memory v7.0  (LOCAL, 38.8 ms, MIT)
  95.0% ┤  ████  ← Mastra "Observational"    (cloud)
        │  ████
        │  ████
  85.4% ┤  ████  ← Supermemory                (cloud, $0.01/1k tok)
        │  ████
        │  ████
        │  ████
   80%  ┤  ████
        └──────────────────────────────────────────

Reproducible: evals/longmemeval-2026-04-17.json · Runner: benchmarks/longmemeval_bench.py

Per-question-type breakdown (R@5 recall_any)

LoCoMo benchmark (new in v9)

Public LoCoMo benchmark (snap-research/locomo, 1986 QA across 10 long-running conversations, the dataset Mem0 / Memobase / Zep / MemMachine publish against):

              LoCoMo Acc (overall, no adversarial)
              ─────────────────────────────────────
  85% ─┤  ████  ← MemMachine        (commercial)
       │  ████
  80%  ┤  ████
       │  ████
  75%  ┤  ████  ← Memobase
       │  ████  ← Zep / Graphiti
       │  ████
  70%  ┤  ████
       │  ████
  67%  ┤  ████  ← Mem0
       │  ████
       │  ████  ← total-agent-memory v9.0  (LOCAL, MIT, gpt-4o-mini)
  60%  ┤  ████
  59%  ┤  ████  ← total-agent-memory (0.596)
       │  ████  ← LangMem (0.581)
  55%  ┤  ████
       └──────────────────────────────────────────

Per-category breakdown (v9.0, gpt-4o-mini gen + judge):

We lead on adversarial (0.998 vs Memobase 0.90) thanks to judge-weighted ensemble + abstain logic. Top-3 leaders win on cat 1/2 via subject-aware profile retrieval — that's our v10 target.

Reproducible: benchmarks/results/v9_diag_v1_*.json · Runner: benchmarks/locomo_bench_llm.py (15 ablation flags). Cost on gpt-4o-mini: ~$5 for full 1986 QA run with ensemble=3.

Latency profile

  p50 (warm)   ▌ 0.065 ms
  p95 (warm)   ▌▌ 2.97 ms
  LongMemEval  ▌▌▌▌▌ 38.8 ms/query   ← includes embedding + CrossEncoder rerank
  p50 (cold)   ▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌▌ 1333 ms  ← first query after process start

Warm / cold reproducible from evals/results-2026-04-17.json.

Competitor comparison

We're not replacing chatbot memory — we're occupying the coding-agent + MCP + local niche.

Full side-by-side with pricing, latency, accuracy, "when to pick each" → docs/vs-competitors.md.

What you get

Eight capabilities nobody else ships

Plus the basics done well

• 6-stage hybrid retrieval (BM25 + dense + fuzzy + graph + CrossEncoder + MMR, RRF fusion) — 96.2% R@5 public
• Multi-representation embeddings — each record embedded as raw + summary + keywords + questions + compressed
• AST codebase ingest — tree-sitter across 9 languages (Python, TS/JS, Go, Rust, Java, C/C++, Ruby, C#)
• Auto-reflection pipeline — memory_save → LaunchAgent file-watch → graph edges appear ~30 s later
• rtk-style content filters — strip noise from pytest / cargo / git / docker logs while preserving URLs, paths, code
• 3D WebGL knowledge graph viewer — 3,500+ nodes, 120,000+ edges, click-to-focus, filters
• Hive plot & adjacency matrix — alternate graph views sorted by node type
• A2A protocol — memory shared between multiple agents (backend + frontend + mobile in a team)
• `design-explore` skill — drop-in Claude Code skill that walks L3-L4 tasks through options → criteria matrix → save_decision before code (see examples/skills/design-explore/SKILL.md)
• `<private>...</private>` inline redaction in any saved content
• Cloud LLM/embed providers with per-phase routing (OpenAI / Anthropic / OpenRouter / Together / Groq / Cohere / any OpenAI-compat)
• `activeContext.md` Obsidian projection for human-readable session state
• Phase-scoped rules (self_rules_context(phase="build")) — ~70% token reduction

Architecture

                  ┌─────────────────────────────────────────────────┐
                  │             Your AI coding agent                │
                  │   (Claude Code · Codex CLI · Cursor · any MCP)  │
                  └──────────────────────┬──────────────────────────┘
                                         │ MCP (stdio or HTTP)
                                         │ 60+ tools
                  ┌──────────────────────▼──────────────────────────┐
                  │            total-agent-memory server             │
                  │    ┌──────────────┐  ┌────────────────────┐     │
                  │    │ memory_save  │  │  memory_recall      │     │
                  │    │ memory_upd   │  │  6-stage pipeline:  │     │
                  │    │ kg_add_fact  │  │  BM25  (FTS5)       │     │
                  │    │ learn_error  │  │  + dense (FastEmbed)│     │
                  │    │ file_context │  │  + fuzzy            │     │
                  │    │ workflow_*   │  │  + graph expansion  │     │
                  │    │ analogize    │  │  + CrossEncoder †   │     │
                  │    │ ingest_code  │  │  + MMR diversity †  │     │
                  │    └──────┬───────┘  │  → RRF fusion       │     │
                  │           │          └──────────┬──────────┘     │
                  └───────────┼─────────────────────┼────────────────┘
                              │                     │
                  ┌───────────▼─────────────────────▼────────────────┐
                  │                   Storage                         │
                  │  ┌────────────┐  ┌────────────┐  ┌─────────────┐ │
                  │  │  SQLite    │  │  FastEmbed │  │   Ollama    │ │
                  │  │  + FTS5    │  │  HNSW      │  │  (optional) │ │
                  │  │  + KG tbls │  │  binary-q  │  │  qwen2.5-7b │ │
                  │  └────────────┘  └────────────┘  └─────────────┘ │
                  └───────────────────────────────────────────────────┘
                              │
                              │ file-watch + debounce
                  ┌───────────▼────────────────────────────────────┐
                  │  Auto-reflection pipeline  (LaunchAgent)        │
                  │  triple_extraction → deep_enrichment → reprs   │
                  │  (async, 10s debounce, drains in background)   │
                  └─────────────────────────────────────────────────┘
                              │
                  ┌───────────▼─────────────────────────────────────┐
                  │  Dashboard (localhost:37737)                     │
                  │   /           - stats, savings, queue depths   │
                  │   /graph/live - 3D WebGL force-graph           │
                  │   /graph/hive - D3 hive plot                   │
                  │   /graph/matrix - adjacency matrix             │
                  └─────────────────────────────────────────────────┘

  † CrossEncoder + MMR are on-demand via `rerank=true` / `diverse=true`

Install

Quickstart — pick one (v12.2.0)

All six channels land at the same MCP server. The npx and ./install.sh paths additionally configure IDE-specific MCP entries and hooks. Other channels start the server bare — you wire the IDE afterwards (see docs/installation.md).

Upgrade from v11.x? Whatever channel you pick will auto-migrate ~/.claude-memory/ → ~/.tam/ on first run and keep a symlink for backward compat. No manual data move required.

Detailed paths (manual / Docker / per-IDE)

Two manual paths. Same 60+ tools, same dashboard, different deployment shapes.

IDE matrix (v10.5)

The same MCP server, same tools, same protocol — different installation locations and hook wiring per IDE. The installer (install.sh --ide <name>) automates all of it.

¹ Aider has no MCP yet — the bridge is via lookup_memory.sh / save_memory.sh shell scripts.

Full per-IDE setup, manual fallbacks, and template snippets: skills/memory-protocol/references/ide-setup.md.

Platform matrix

Full per-platform walkthrough, WSL2 Windows-host-vs-WSL IDE nuances, the wsl -e MCP-command pattern, IDE coverage matrix, and uninstall/diagnostic flows: [docs/installation.md](docs/installation.md).

Path A — native (macOS / Linux / WSL2)

git clone https://github.com/vbcherepanov/total-agent-memory.git ~/total-agent-memory
cd ~/total-agent-memory
bash install.sh --ide claude-code   # or: cursor | gemini-cli | opencode | codex

The installer:

1. Clones + creates ~/total-agent-memory/.venv/
2. Installs deps from requirements.txt and requirements-dev.txt
3. Pre-downloads the FastEmbed multilingual MiniLM model
4. Registers the MCP server via claude mcp add-json memory ... (stored in ~/.claude.json, the canonical store Claude Code actually reads)
5. Copies all hooks (session-*, user-prompt-submit.sh, post-tool-use.sh, pre-edit.sh, on-bash-error.sh, etc.) into ~/.claude/hooks/ and registers them in ~/.claude/settings.json
6. Grants permissions.allow for 20+ mcp__memory__* tools so hook-driven calls don't prompt for confirmation
7. Installs background services for the current OS:

• macOS — 4 LaunchAgents (reflection, orphan-backfill, check-updates, dashboard) under ~/Library/LaunchAgents/
• Linux / WSL2 — 7 systemd --user units (*.service, *.timer, *.path) under ~/.config/systemd/user/; gracefully degrades if systemd --user is unavailable (WSL without /etc/wsl.conf)

1. Applies all migrations to a fresh memory.db
2. Starts the dashboard at http://127.0.0.1:37737

Restart Claude Code → /mcp → memory should show Connected with 60+ tools.

Path A — native (Windows 10/11)

git clone https://github.com/vbcherepanov/total-agent-memory.git $HOME\total-agent-memory
cd $HOME\total-agent-memory
powershell -ExecutionPolicy Bypass -File install.ps1 -Ide claude-code

Same 9 steps as Unix, but:

• MCP config path is %USERPROFILE%\.claude\settings.json (or .cursor\mcp.json, etc.)
• Hooks copied to %USERPROFILE%\.claude\hooks\ — .ps1 versions (auto-capture, memory-trigger, user-prompt-submit, post-tool-use, pre-edit, on-bash-error, session-start/end, on-stop, codex-notify)
• Background services via Task Scheduler:
• total-agent-memory-reflection — every 5 min (no native FileSystemWatcher equivalent)
• total-agent-memory-orphan-backfill — daily 00:00 + 6h repetition
• total-agent-memory-check-updates — weekly Mon 09:00
• TotalAgentMemoryDashboard — AtLogon

Uninstall

All installers preserve ~/.tam/memory.db (legacy installs: ~/.claude-memory/memory.db) and your config files; only services + hook registrations are removed.

./install.sh --uninstall          # macOS/Linux/WSL2 — removes LaunchAgents OR systemd units
.\install.ps1 -Uninstall          # Windows — unregisters Scheduled Tasks + cleans settings.json

Diagnose

One-shot health check — prints ✓/✗ for each subsystem (OS detect, venv, MCP import, services, dashboard HTTP, Ollama, DB migrations):

bash scripts/diagnose.sh          # macOS / Linux / WSL2
.\scripts\diagnose.ps1            # Windows

Exit code 0 = all green, 1 = something broken.

Path B — Docker (everything containerized, cross-platform)

git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
bash install-docker.sh --with-compose

Brings up 5 services:

First run pulls qwen2.5-coder:7b (~4.7 GB) + nomic-embed-text (~275 MB) — 5–10 min cold start.

GPU note: Docker Desktop on macOS doesn't forward Metal. Native install is faster on Mac. On Linux with NVIDIA Container Toolkit, uncomment the deploy.resources.reservations.devices block in docker-compose.yml.

Verify (both paths)

memory_save(content="install works", type="fact")
memory_stats()

Open <http://127.0.0.1:37737/> — dashboard, knowledge graph, token savings.

Quick start

v11 default is `MEMORY_MODE=fast`. No LLM, no Ollama, no network in the save/search/recall hot path. To restore v10.5 synchronous-LLM behaviour set export MEMORY_MODE=deep. Mode switching: LAUNCH.md § Tuning.

Once installed, in any Claude Code / Codex CLI / Cursor session:

1. Resume where you left off (auto on session start, but you can also invoke)

session_init(project="my-api")
→ {summary: "yesterday: migrated auth middleware to JWT",
   next_steps: ["update OpenAPI spec", "notify frontend team"],
   pitfalls: ["don't revert migration 0042 — dev DB already migrated"]}

2. Save a decision (agent does this automatically after hooks are registered)

memory_save(
  type="decision",
  content="Chose pgvector over ChromaDB for multi-tenant RLS",
  context="WHY: single Postgres instance, per-tenant row-level security",
  project="my-api",
  tags=["database", "multi-tenant"],
)

3. Recall across sessions / projects

memory_recall(query="vector database choice", project="my-api", limit=5)
→ RRF-fused results from 6 retrieval tiers

4. Predict approach before starting a task

workflow_predict(task_description="migrate auth middleware to JWT-only")
→ {confidence: 0.82, predicted_steps: [...], similar_past: [...]}

5. Check a file's risk before editing (auto via hook, also manual)

file_context(path="/Users/me/my-api/src/auth/middleware.go")
→ {risk_score: 0.71, warnings: ["last 3 edits caused test failures in ..."], hot_spots: [...]}

6. Get full stats

memory_stats()
→ {sessions: 515, knowledge: {active: 1859, ...}, storage_mb: 119.5, ...}

CLI: lookup-memory for sub-agents

New in v9. Bash-friendly memory search for sub-agent workflows where launching the full MCP server would be overkill (e.g. Bash(lookup-memory "fix slow Wave query") from inside a Claude Code agent prompt).

Two equivalent commands ship with the package (registered as [project.scripts] entries — installed automatically by ./install.sh or ./update.sh):

lookup-memory "Caroline researched"          # human-readable bullets
tam-lookup "Caroline researched"             # short canonical alias
ctm-lookup "Caroline researched"             # legacy alias (v11.x and earlier)

lookup-memory --project myproj --limit 5 "auth flow"
lookup-memory --type solution --tag reusable "fix bug"
lookup-memory --json "claude code hooks"     # structured stdout for piping

How it works: opens the same $TAM_MEMORY_DIR/memory.db (legacy: $CLAUDE_MEMORY_DIR/memory.db) the running MCP server uses → BM25 ranking via FTS5 → falls back to LIKE on older DBs. Zero deps beyond the package. No Ollama, no rag_chat.py, no ChromaDB required for the CLI path. Works on macOS, Linux, Windows.

$ lookup-memory --project locomo_0 --limit 2 "adoption"
1. [synthesized_fact|locomo_0] Caroline is researching adoption agencies.
2. [synthesized_fact|locomo_0] Melanie congratulates Caroline on her adoption.

Why three names? lookup-memory matches the legacy bash script that older docs and sub-agent prompts reference (~/claude-memory-server/ollama/lookup_memory.sh, legacy install path). tam-lookup is the new project-prefixed canonical form (v12+). ctm-lookup is the v11.x prefixed name, kept as a legacy alias. All three call into total_agent_memory.lookup:main (v11.x and earlier: claude_total_memory.lookup:main, still importable via deprecation shim).

Migration note: v7/v8 docs that pointed at ~/claude-memory-server/ollama/lookup_memory.sh should be updated — the bash version still works for users with a manual install, but ./install.sh / ./update.sh clients on v9+ now get lookup-memory (and tam-lookup) on PATH directly via the package's [project.scripts] entry.

MCP tools reference (60+ tools)

Tool categories

Core retrieval (9): memory_save, memory_recall, memory_get, memory_update, memory_delete, memory_history, memory_extract_session, memory_relate, memory_search_by_tag

Knowledge graph (8): kg_add_fact, kg_invalidate_fact, kg_at, kg_timeline, memory_graph, memory_graph_index, memory_graph_stats, memory_concepts

Episodic / session (6): memory_episode_save, memory_episode_recall, session_init, session_end, memory_timeline, memory_history

Procedural / workflows (4): workflow_learn, workflow_predict, workflow_track, classify_task

Task phases (4, v8.0): task_create, phase_transition, task_phases_list, complete_task

Decisions (1, v8.0): save_decision

Intents (3, v8.0): save_intent, list_intents, search_intents

Self-improvement (5): self_rules, self_rules_context, self_insight, self_patterns, self_error_log, rule_set_phase (v8.0)

Pre-edit guard / error learning (3): file_context, learn_error, self_error_log

Analogy / cross-project (2): analogize, ingest_codebase

Reflection / consolidation (4): memory_reflect_now, memory_consolidate, memory_forget, memory_observe

Stats / export (5): memory_stats, memory_export, memory_self_assess, memory_context_build, benchmark

Skills (3): memory_skill_get, memory_skill_update, file_context

Total: 60+ tools. Each is documented below with input schema and example.

Token-efficient 3-layer workflow

When you only know the topic but not which records matter, use progressive disclosure:

1. Index — memory_recall(query="auth refactor", mode="index", limit=20) → ~2 KB of {id, title, score, type, project, created_at} per hit. No content, no cognitive expansion.
2. Timeline — memory_recall(query="auth refactor", mode="timeline", limit=5, neighbors=2) → top-K hits padded with ±neighbours from the same session, sorted chronologically.
3. Fetch — memory_get(ids=[3622, 3606]) → full content for ONLY the IDs you chose (max 50 per call, detail="summary" truncates to 150 chars).

Typical saving: 80-90 %% fewer tokens vs memory_recall(detail="full", limit=20) when you end up using 2-3 of the 20 hits.

<details> <summary><b>Core memory (15)</b></summary>

memory_recall · memory_get · memory_save · memory_update · memory_delete · memory_search_by_tag · memory_history · memory_timeline · memory_stats · memory_consolidate · memory_export · memory_forget · memory_relate · memory_extract_session · memory_observe

</details>

<details> <summary><b>Knowledge graph (6)</b></summary>

memory_graph · memory_graph_index · memory_graph_stats · memory_concepts · memory_associate · memory_context_build

</details>

<details> <summary><b>Episodic memory & skills (4)</b></summary>

memory_episode_save · memory_episode_recall · memory_skill_get · memory_skill_update

</details>

<details> <summary><b>Reflection & self-improvement (7)</b></summary>

memory_reflect_now · memory_self_assess · self_error_log · self_insight · self_patterns · self_reflect · self_rules · self_rules_context

</details>

<details> <summary><b>Temporal knowledge graph (4)</b></summary>

kg_add_fact · kg_invalidate_fact · kg_at · kg_timeline

</details>

<details> <summary><b>Procedural memory (3)</b></summary>

workflow_learn · workflow_predict · workflow_track

</details>

<details> <summary><b>Pre-flight guards & automation (8)</b></summary>

file_context (pre-edit risk scoring) · learn_error (auto-consolidating error capture) · session_init / session_end · ingest_codebase (AST, 9 languages) · analogize (cross-project analogy) · benchmark (regression gate)

</details>

Full JSON schemas: python -m total_agent_memory.cli tools --json or open the dashboard at localhost:37737/tools.

TypeScript SDK

For Node.js / browser / any TS project that isn't an MCP-native agent:

npm i @vbch/total-agent-memory-client

import { connectStdio } from "@vbch/total-agent-memory-client";

const memory = await connectStdio();

await memory.save({
  type: "decision",
  content: "Picked pgvector over ChromaDB for multi-tenant RLS",
  project: "my-api",
});

const hits = await memory.recallFlat({
  query: "vector database choice",
  project: "my-api",
  limit: 5,
});

Also ships LangChain adapter example, procedural-memory integration, and HTTP transport (for team / serverless setups).

Package repo: github.com/vbcherepanov/total-agent-memory-client

Dashboard (localhost:37737)

• `/` — live stats, queue depths, token savings from filters, representation coverage
• `/graph/live` — 3D WebGL force-graph (Three.js), 3,500+ nodes / 120,000+ edges, click-to-focus, type filters, search
• `/graph/hive` — D3 hive plot, nodes on radial axes by type
• `/graph/matrix` — canvas adjacency matrix sorted by type
• `/knowledge` — paginated knowledge browser, tag filters
• `/sessions` — last 50 sessions with summaries + next steps
• `/errors` — consolidated error patterns
• `/rules` — active behavioral rules + fire counts
• SSE-pill in header — live reconnect indicator

Screenshots → docs/screenshots/ (coming)

Update

cd ~/total-agent-memory   # legacy clones: ~/claude-memory-server
./update.sh

7 stages:

1. Pre-flight — disk check + DB snapshot (keeps last 7)
2. Source pull (git) or SHA-256-verified tarball
3. Deps — pip install -r requirements.txt -r requirements-dev.txt (only if hash changed)
4. Full pytest suite — aborts with snapshot if red
5. Schema migrations — python src/tools/version_status.py
6. LaunchAgent reload — reflection + backfill + update-check
7. MCP reconnect notification — in-app /mcp → memory → Reconnect

Manual equivalent:

cd ~/total-agent-memory   # legacy clones: ~/claude-memory-server
git pull
.venv/bin/pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/python src/tools/version_status.py
.venv/bin/python -m pytest tests/
# in Claude Code: /mcp → memory → Reconnect

Upgrading from v8.x to v9.0

v9 is backward compatible. Existing v8 calls and DB schema work unchanged — v9 is an infra release that adds pluggable backends, a public CLI for sub-agents, and LoCoMo benchmark wiring. Nothing is forcibly enabled.

One-command upgrade

cd ~/total-agent-memory && ./update.sh   # legacy clones: ~/claude-memory-server
# pulls v9 src, installs new entry-points (tam, tam-lookup, lookup-memory; legacy: ctm-lookup),
# keeps existing memory.db untouched.

After upgrade, verify the new CLI is on PATH:

lookup-memory --limit 1 "any-query-from-your-history"

What's new (no action required)

• `lookup-memory` / `tam-lookup` / `ctm-lookup` (legacy) CLI now installed alongside total-agent-memory MCP server (registered as [project.scripts] so ./install.sh and ./update.sh put them on PATH automatically). Sub-agent prompts that reference the legacy ~/claude-memory-server/ollama/lookup_memory.sh script keep working; new prompts should prefer the package-installed name.
• Embedding backends stay on fastembed by default. Switch via V9_EMBED_BACKEND=openai-3-large (set MEMORY_EMBED_API_KEY) — costs ~$0.10/5k rows for re-embed, expected R@5 lift on conversational data.
• Reranker backend stays on ce-marco by default. V9_RERANKER_BACKEND=bge-v2-m3 (or off) switches at runtime.
• Subject-aware retrieval is opt-in via --subject-aware in benchmarks/locomo_bench_llm.py. Future: surface as MCP tool flag.
• No migrations. Schema unchanged from v8.

What requires manual action

• Re-embed (only if switching embedding model, otherwise skip):

  python -m scripts.reembed --backend openai-3-large --confirm

• Old bash sub-agent prompts that hardcode ~/claude-memory-server/ollama/lookup_memory.sh "query" will keep working. To ride the new package install, replace with lookup-memory "query".

Breaking changes

None. All v8 MCP tools, env vars, hooks, and DB tables behave identically.

Upgrading from v7.x to v8.0

v8.0 is backward compatible — your existing v7 installation keeps working unchanged. All new features are opt-in via MCP tool calls or env vars.

One-command upgrade

cd ~/total-agent-memory && ./update.sh   # legacy clones: ~/claude-memory-server
# Applies migrations 011-013 idempotently, restarts LaunchAgents, updates dependencies

Then restart Claude Code: /mcp restart memory.

What changes automatically

• Migrations 011–013 apply on MCP startup (privacy_counters, task_phases, intents). Zero-downtime, idempotent.
• Existing `memory_save` calls keep working — they now additionally strip <private>...</private> sections if present.
• Existing `memory_recall` calls keep working — default mode is still "search". New mode="index" is opt-in.
• Existing `session_end` calls keep working — auto_compress=False by default. Pass auto_compress=True to opt in.
• Existing `self_rules_context` calls keep working — default returns all rules (no phase filter).

What requires manual setup

1. Cloud providers (only if you want to replace/augment Ollama):

export MEMORY_LLM_PROVIDER=openai       # or "anthropic"
export MEMORY_LLM_API_KEY=sk-...
export MEMORY_LLM_MODEL=gpt-4o-mini     # or "claude-haiku-4-5"

See Cloud providers for OpenRouter / per-phase routing / Cohere examples.

2. Install additional hooks (for UserPromptSubmit capture + citation):

./install.sh --ide claude-code   # re-run installer; it now registers user-prompt-submit.sh hook

The hook is additive — existing hooks keep working.

3. activeContext.md Obsidian integration (if you want markdown projection):

export MEMORY_ACTIVECONTEXT_VAULT=~/Documents/project/Projects   # default
# Disable: export MEMORY_ACTIVECONTEXT_DISABLE=1

Each session_end writes <vault>/<project>/activeContext.md.

Breaking changes

None. All v7 MCP tool signatures are preserved. New parameters are optional with safe defaults.

Embedding dimension note

If you switch to a cloud embedding provider (MEMORY_EMBED_PROVIDER=openai/cohere), the server will refuse to start if existing DB embeddings have a different dimension than the new provider returns. This is deliberate — it prevents silent data corruption.

Either:

• Keep MEMORY_EMBED_PROVIDER=fastembed (default 384d) and only change the LLM provider, OR
• Re-embed the DB: python src/tools/reembed.py --provider openai --model text-embedding-3-small

New MCP tools in v8.0

Quick reference — see full docs in MCP tools reference:

Extended tools:

• memory_recall(mode="index"|"timeline", decisions_only=False, ...) — 3-layer token-efficient workflow
• session_end(auto_compress=True, transcript=None, ...) — LLM-generated summary
• self_rules_context(phase="build"|"plan"|...) — phase filter
• save_knowledge(...) — now strips <private>...</private> sections automatically

Rollback plan

v8.0 doesn't remove any v7 functionality. If you hit an issue, you can:

1. Set env var to revert behaviour:

   export MEMORY_LLM_PROVIDER=ollama           # revert to local LLM
   export MEMORY_EMBED_PROVIDER=fastembed      # revert to local embeddings
   export MEMORY_ACTIVECONTEXT_DISABLE=1       # disable markdown projection
   export MEMORY_POST_TOOL_CAPTURE=0           # disable opt-in capture (default anyway)

1. Migrations 011/012/013 are additive (no DROP / ALTER on existing tables), so DB downgrade is not destructive — old code continues reading older tables.

1. Worst case: git checkout v7.0.0 && ./update.sh --skip-migrations.

Ollama setup (optional but recommended)

Without Ollama: works fully — raw content is saved, retrieval via BM25 + FastEmbed dense embeddings.

With Ollama: you also get LLM-generated summaries, keywords, question-forms, compressed representations, and deep enrichment (entities, intent, topics).

brew install ollama     # or: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull qwen2.5-coder:7b        # default — best quality/speed on M-series
ollama pull nomic-embed-text        # optional, alternative embedder

Cloud providers (optional)

Use OpenAI, Anthropic, or any OpenAI-compat endpoint (OpenRouter, Together, Groq, DeepSeek, LM Studio, llama.cpp) instead of local Ollama.

OpenAI:

export MEMORY_LLM_PROVIDER=openai
export MEMORY_LLM_API_KEY=sk-...
export MEMORY_LLM_MODEL=gpt-4o-mini

Anthropic:

export MEMORY_LLM_PROVIDER=anthropic
export MEMORY_LLM_API_KEY=sk-ant-...
export MEMORY_LLM_MODEL=claude-haiku-4-5

OpenRouter (100+ models via one endpoint):

export MEMORY_LLM_PROVIDER=openai
export MEMORY_LLM_API_BASE=https://openrouter.ai/api/v1
export MEMORY_LLM_API_KEY=sk-or-...
export MEMORY_LLM_MODEL=anthropic/claude-haiku-4.5

Per-phase routing (cheap model for bulk, quality for compression):

export MEMORY_TRIPLE_PROVIDER=openai
export MEMORY_TRIPLE_MODEL=gpt-4o-mini
export MEMORY_ENRICH_PROVIDER=anthropic
export MEMORY_ENRICH_MODEL=claude-haiku-4-5

Embeddings (dimension must match existing DB or re-embed required):

export MEMORY_EMBED_PROVIDER=openai
export MEMORY_EMBED_MODEL=text-embedding-3-small  # 1536d
# or Cohere:
export MEMORY_EMBED_PROVIDER=cohere
export MEMORY_EMBED_API_KEY=...

Model choice

Configuration

Environment variables (all optional):

v11.0 — Memory mode + multi-embedding-space

v10 + earlier

CPU-only / WSL hosts: if Ollama keeps timing out, lower MEMORY_TRIPLE_MAX_PREDICT before raising timeouts. install-codex.sh writes conservative defaults automatically. For 30-40s save latency on WSL2 → set `MEMORY_ASYNC_ENRICHMENT=true` — see below.

Full config: see total_agent_memory/config.py.

Performance tuning

v11.0 fast-mode hot path (default)

When MEMORY_MODE=fast (default):

llm_calls=0, network_calls=0. Reproduce: ./bin/memory-bench. Regression gate: ./bin/memory-perf-gate. Architecture rationale and per-stage audit: docs/v11/audit.md. Raw bench artifact: docs/v11/benchmark.md.

If your numbers do not match the table, run ./bin/memory-bench --warmup first — cold FastEmbed import dominates the first call.

Legacy: v10.5 deep-mode memory_save latency

The synchronous v10 hot path runs five LLM-bound stages inline so a drop verdict can block the INSERT and a contradiction supersede commits in the same transaction. On macOS with a warm Ollama that's ~340 ms median; on a WSL2 box without GPU/CoreML each LLM round-trip can stretch the same call into 30–40 seconds.

v10.1 ships an opt-in inbox/outbox worker that moves the heavy stages out of band:

sync   : privacy → canonical_tags → INSERT → embed → enqueue → return
worker : quality_gate → entity_dedup_audit → contradiction → episodic → wiki

Enable it in your env:

export MEMORY_ASYNC_ENRICHMENT=true
# Optional knobs (defaults shown):
export MEMORY_ENRICH_TICK_SEC=0.1
export MEMORY_ENRICH_BATCH=5
export MEMORY_ENRICH_MAX_ATTEMPTS=3
export MEMORY_ENRICH_STALE_AFTER_SEC=60

Restart the MCP server. A background daemon thread now consumes enrichment_queue; you can watch it on the dashboard panel ⚡ v10.1 enrichment worker.

Bench v10.5 (10-record corpus × 2 rounds, with LLM stages on)

memory_save latency:

memory_recall latency: p50 ≈ 3-5 ms in both modes (steady state), with cold-cache p95 outliers on the first warmup hit.

p95 collapses 80× with async (2150 ms → 27 ms). On WSL2 with a slow Ollama, the same shape holds — sync p95 of 30-40 s becomes async p95 of ~300-1000 ms (LLM moves out of the hot path entirely).

Reproduce: ./.venv/bin/python benchmarks/v10_5_latency.py --rounds 2 --with-llm. Full report: benchmarks/v10_5_results.md.

Trade-off — soft drop semantic

When async is on, a quality_gate drop no longer prevents the INSERT (we already committed in the sync path). Instead the row is marked status='quality_dropped' after the worker scores it. memory_recall ignores that status (idx_knowledge_status_quality is added in migration 020). Audit history stays in quality_gate_log so nothing is lost.

If you need strict pre-INSERT gating (e.g. compliance), keep the default sync path.

Crash recovery

Rows stuck in processing longer than MEMORY_ENRICH_STALE_AFTER_SEC (default 60 s) are flipped back to pending automatically — covers worker process kills mid-stage. The pre-existing write_intents outbox still covers a crash before INSERT.

Roadmap

Shipped in v11.0 (2026-04-27) — production memory engine

• ✅ Default `MEMORY_MODE=fast` — zero LLM, zero Ollama, zero network in save/search/recall hot path. Set MEMORY_MODE=deep to restore v10.5 behaviour.
• ✅ Memory Core / AI Layer split — src/memory_core/* is deterministic; src/ai_layer/* owns every LLM-bound code path. Enforced by tests/test_no_llm_hot_path.py.
• ✅ 4 modes: ultrafast / fast / balanced / deep. Single env flag.
• ✅ Multi-embedding-space contract — every vector row records provider / model / dimension / space / content_type / language. Spaces: text / code / log / config. Single Chroma backend; per-space model swap is config-only.
• ✅ Embed fallback ladder gated — silent Ollama fallback in Store.embed requires `MEMORY_ALLOW_OLLAMA_IN_HOT_PA