Personal, team and shared memory
One authenticated server holds all three scopes, each with its own database, graph and index. Saves are personal by default; search covers every scope you can access.
v14.9.0 ·
MCP 2026-07-28
·
3,873 tests passing
Memory your agent actually keeps.
Persistent memory for Claude Code, Codex CLI, Cursor and any MCP client. Local-first, no LLM in the default recall path — and since 14.0, personal, team and shared memory on one server. 0.607 R@5 on LoCoMo and 0.448 on BEAM at the 1M-token scale, measured on 13.x — retrieval numbers you can reproduce on your laptop, without an API key.
- 0.607LoCoMo retrieval R@5 · 13.x
- 0.448BEAM 1M retrieval R@5 · 13.x
- 0.065 msWarm cached p50
- 100 %Local by default
~ — claude-code
# Day 1 — Tuesday
You: remember we picked pgvector over ChromaDB
because of multi-tenant RLS.
Claude: ✓ memory_save(type="decision",
tags=["reusable", "db"])
# Day 4 — different session, different repo
You: why did we pick pgvector again?
Claude: ✓ memory_recall(query="vector db choice")
→ Chose pgvector over ChromaDB.
WHY: single Postgres, per-tenant RLS.
Tagged reusable. Created 2026-05-12.
# fast mode · 0 LLM calls · 0 network claude-code codex cursor cline continue windsurf gemini-cli opencode aider
$ /plugin marketplace add vbcherepanov/total-agent-memory$ npx -y total-agent-memory$ uvx total-agent-memory$ pipx install total-agent-memory$ brew install vbcherepanov/tap/total-memory$ curl -fsSL https://get.totalmemory.dev | sh$ docker run -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.7.0 then /plugin install total-agent-memory@vbcherepanov — server, skill and hooks in one stepwrapper 1.9.1 bootstraps server 14.7.0 in ~/.tam/.venv · needs Python 3.11+one-off run via uv, nothing installed · Python 3.11+isolated install from PyPI · Python 3.11+ · adds tam, tam-team and tam-remotemacOS / Linux via Homebrew · formula 14.7.0POSIX script — uses npx, uvx, pipx or python3, whichever is presentlinux/amd64 + linux/arm64 · public image on GitHub Container Registry · dashboard on :37737
No registration. No telemetry. MIT licensed. Base install ~113 MB of wheels, no torch.
Step-by-step setup per client →
New in 14.9.0 · 2026-10-13
Memory that works while the agent never calls a memory tool.
The hooks now do the recall, the rule checking and the saving themselves. Every prompt gets the rules that match it and a short block of relevant records, inside a 400-token budget and a 1.5 s limit, without ever blocking the prompt. At the end of a turn the agent's actions are checked against the rules it was shown: a broken "never X" is reported, and the verdicts go to separate heuristic counters that never touch explicit ratings or suspension. A prompt that corrects the agent ("I already told you…") becomes a draft insight, promotable to a rule only after real upvotes. Loading rules no longer counts as firing them, which used to suspend helpful rules after ten session starts.
One warm server can now serve every client: the first memory_recall of a session takes 0.18 s
through tam proxy instead of 1.51 s for a cold stdio server. A search while another connection held
the write lock went from about 1,050 ms to 16 ms. LongMemEval-S held-out: 88.0 on 400 questions with a gpt-4.1-mini reader
(results); the other recall changes left LoCoMo and
LongMemEval-S dev R@10 unchanged (measurements).
The catalogue grows from 77 to 79 tools with
memory_exploration_record and
memory_exploration_recall,
codebase conclusions that go stale when their files change; migrations 038–042 run on first start.
- Ambient memory Every prompt gets the matching rules and a short block of relevant records (400 tokens, 1.5 s, never blocking the prompt). A new PreToolUse hook shows a rule right before a command or edit it applies to; every tool call lands in a bounded, redacted action log.
- Rules measured against actions At Stop the turn is checked against the rules shown to the session, and a broken "never X" is reported.
self_rules(action='report')gives follow rates with 95% Wilson intervals; suspension now rests on explicit ratings only. - Shared warm daemon
tam daemon start|stop|statusruns one warm server per memory directory; clients launchtam proxy. Firstmemory_recallof a session: 0.18 s instead of 1.51 s.TAM_TOOL_PROFILE=lean|minimallists 28 or 12 tools. - Recall Relative dates ("last month", "three weeks ago") give the temporal re-ranker a window, from now or from
memory_recall(as_of=...). "What was it before?" questions rank the older value first: 0 of 48 before, 48 of 48 now. - Import and export
tam import chatgpt|claude|mem0|markdownkeeps original timestamps and skips what was already imported;tam export --encryptedandtam import-bundlemove a store between machines as an AES-256-GCM bundle. - Windows, and CI on every OS Every pull request runs the full suite on Ubuntu, macOS and Windows with Python 3.11 to 3.13, all blocking, plus ruff, CodeQL and the recall-quality gate. Bundle replace,
file:///C:/...replicas and team server shutdown now work on Windows.
14.8.0 · 2026-10-08
Every recall tier measured, two of them fixed.
Tier weights became configuration, and an ablation harness found a graph tier that had never fired and a representation tier that scored only the first 100 rows. Both are fixed: on a copy of the author's store R@10 rose from 0.133 to 0.167 and the p50 recall fell from 336 ms to 128 ms (results).
- Tier weights are configuration
MEMORY_RECALL_TIER_WEIGHTS=fts=1,semantic=1.2,fuzzy=0names any tier;0skips it.memory_explain_searchreports the weights in use, andbenchmarks/tier_ablation.pymeasures them on LoCoMo, LongMemEval-S or a copy of your store. - Two tiers fixed The graph tier read a table nothing writes and never fired; it now walks the knowledge graph. The representation tier scored the first 100 rows in table order; it now scores every row of the scope.
- Questions the ranking missed Advice-shaped questions also search the project's conventions and favour the user's own turns;
session_endkeeps its summary as anoterecord that later recalls find. - LLM fallback chain
MEMORY_LLM_FALLBACK_PROVIDERS=anthropic,openai: every enrichment phase uses the first provider that answers.memory_statsreports the chain, the pending queue rows and astalledflag. - Consolidation on personal installs The hourly reflection job now materialises episodes, merges duplicates and decays stale facts for idle projects; before, this ran only on the team server.
- Pinned tool contract A test pins the 77 tool schemas and behaviour hints. Nothing in the Claude Code plugin, the hooks or the skill changed in this release.
What's new in 14
Personal, team and shared memory on one server.
Released 2026-09-15. Local single-user mode is unchanged. 14.0.0 adds an authenticated
team server, and it requires Python 3.11 or newer. 14.1.0 added a contradiction-seeking second
search to memory_answer. 14.2.0 (2026-09-21) answers with the latest
value of a fact that changed over time: the reader sees when each record was saved, so
“Mary loves red”, followed later by “now green”, answers green, previously red. LongMemEval
knowledge-update rose from 12/78 to 35/78 with Claude Haiku 4.5; timestamps are stored in one UTC format.
14.3.0 can run the contradiction check on TypeSafe's Jev
(MEMORY_CONTRADICTION_SCORER=jev): same accuracy, the check drops from 3.1 s to
1.9 s, and Jev billed $0.04 for all 78 questions. 14.3.1 keeps fact updates that 14.3.0's dedup
dropped ("… is Argentina" → "… is Armenia") and keeps project-scoped recall fast as a store grows:
at 100k records 25 ms instead of 781 ms, at 1M 105 ms instead of seconds;
MCP_HTTP_WORKERS runs several HTTP server processes on one port.
14.5.0 (2026-09-23) shows no statistically significant difference from Mem0 Platform when both are graded on
the same held-out questions, with the same judge model and prompt for both in each grading configuration:
LongMemEval-S 92.25 vs 91.00, LoCoMo 88.02 vs 88.46 — not a proof of equivalence
(report and reproduction).
It also lets a record retire the value it replaces with
memory_save(supersede=true) (MemoryAgentBench FactConsolidation single-hop 82 → 99),
and writes at 1M records no longer reload the vector cache (next unscoped recall 4.2 s → 0.37 s).
14.5.1 (2026-09-24) keeps a record below its own later update after re-ranking: the new cross-encoder
knew the real-world value and lifted it above the recorded one. On MemoryAgentBench FactConsolidation the
newest value now ranks first for 98 of 100 questions instead of 45
(findings).
Release notes
Authorship and revisions
The personal token identifies author and client. Every edit keeps a revision with author, UTC time and reason; expected_revision stops you overwriting someone else's change.
Remote MCP bridge and web interface
A standard-library-only Python bridge connects an IDE to the team catalogue (8 memory tools, 14 onboarding tools and memory_report); the local catalogue has 79. The team web interface searches, saves, edits and shows history.
Configurable internal LLMs
Route optional internal text tasks to Ollama, an OpenAI-compatible endpoint or Anthropic, and pick a vision model explicitly. Fast mode still needs no LLM.
Lower CPU pressure
Embeddings and optional PyTorch models default to one compute thread. The team server keeps three workspace workers warm instead of reloading models.
Scoped retrieval, opt-in grounded reader
Scope checks run after expansion, vector search uses the model of each embedding space, and private sections never reach write intents. The optional grounded reader rejects contradictory claims; it is not the default answer path.
team server · Linux / macOS
python3 -m venv .venv
. .venv/bin/activate
python -m pip install total-agent-memory==14.9.0
tam-team --root ./team-data user-add alice 'Alice'
tam-team --root ./team-data user-add bob 'Bob'
tam-team --root ./team-data team-add engineering 'Engineering'
tam-team --root ./team-data member alice engineering editor
tam-team --root ./team-data member bob engineering editor
tam-team --root ./team-data token-create alice --client codex --out ./alice.token
tam-team --root ./team-data token-create bob --client cursor --out ./bob.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.
Give each person their own token. For other machines, put an HTTPS reverse proxy in front of the
web interface and /mcp/. Windows, Docker Compose, permissions and backup:
README.
remote IDE · mcpServers
{
"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/alice.token"
}
}
}
}
Copy src/team_memory/remote.py to the client. It uses only the Python
standard library. If the package is installed there, tam-remote works too.
Remote clients get eight memory tools (memory_scopes, memory_save,
memory_recall, memory_get, memory_update,
memory_delete, memory_history, memory_export),
plus memory_report and the onboarding tools since 14.6.0.
Published channels
PyPI total-agent-memory 14.9.0 · npm wrapper 1.9.3, pinned to server 14.9.0 ·
ghcr.io/vbcherepanov/total-agent-memory:14.9.0 for linux/amd64 and arm64 ·
Homebrew vbcherepanov/tap/total-memory 14.9.0 · official MCP Registry
io.github.vbcherepanov/total-agent-memory ·
GitHub Release v14.9.0.
Validation
The 14.0.0 release CI matrix passed on Ubuntu 24.04, Windows 2022, macOS 15 Intel and macOS 15 arm64 with Python 3.11, 3.12 and 3.13. It also passed the Docker Compose, Chromium / Firefox / WebKit browser and unpacked source archive gates. 2,145 tests pass from the source archive. CI run · verification report
35-second demo
The agent remembers on its own.
You don't tell it "save this." It just does. Decisions, lessons, gotchas — captured in the background, recalled in future sessions across different repos.
- Auto-captures decisionsArchitectural choice →
memory_save(decision)without you typing anything. - Auto-learns from errorsTest fails → diagnosis → fix →
learn_error. Same trap won't fire twice. - Auto-recalls across reposDifferent project, fresh session → agent
memory_recalls yesterday's decisions before answering.
tam-demo.mp4 · 1920×1080 · 35s · CC-BY 4.0
1920×1080 · 7:13 · English
Watch on YouTube
7-minute walkthrough
How it works, from install to team server.
Install, run the setup wizard, save a decision in one session and get it back in a new one. Every terminal output in the video is real, recorded in a throwaway folder.
The problem
AI coding agents have goldfish memory.
Yesterday's architectural decisions. Last week's bug fix. The reason you chose pgvector. The reason you didn't pick GraphQL. The stack you settled on at 2am after the third PoC. Close the terminal — and it all vanishes. Every new Claude session starts at zero, and you re-paste the same context. Forever.
CLAUDE.md
Loads everything, every time
Every note loads on every turn, so the file grows until it crowds the window. Then you delete half of it and lose what mattered.
Cloud memory APIs
Your code, their database
Sends every decision, fix, file path through an API key. Latency, lock-in, and a privacy footprint you didn't sign up for.
Agent-managed memory
LLM in the hot path
The model edits its own context. Slow, expensive, non-deterministic, and the retrieval quality is whatever the model felt like that turn.
How it works
Two-layer architecture. The fast one is the default.
memory_core is deterministic — storage, embeddings, vector search, classifier, dedup, telemetry. No LLM imports allowed. Enforced by a unit test.
ai_layer is everything LLM-touching — summarisation, keyword extraction, contradiction detection, reflection, query rewriting. Runs async, off the hot path.
6-stage hybrid retrieval
FTS5 + BM25 + dense + graph + CrossEncoder + MMR with RRF fusion. Tuned on real Claude Code sessions.
Temporal knowledge graph
Nodes & edges auto-extracted on save. Time-aware queries: "what was our stack in Q3?" returns the right answer.
Procedural memory
Recurring error patterns auto-consolidate into rules. Skills accumulate. Workflow predictor learns your loops.
Hot path: zero LLM
memory_core is deterministic. ai_layer enriches async. Warm cached p50 0.065 ms (eval of 2026-04-17). No surprise tokens.
MCP 2026-07-28
Serves the stateless revision and the legacy handshake from one process. Structured results, behaviour annotations on all 79 tools. Nine IDEs, one command each.
Local-first
SQLite + FastEmbed on your machine. No cloud, no telemetry, no API key required. Remote LLM providers are opt-in. MIT licence.
Benchmarks
Numbers we can actually reproduce.
Every value below links to a result file; runners live in benchmarks/. Retrieval numbers were measured on 13.x; the 14.x releases make no new retrieval claim. Figures that competitors publish on a different metric are named, not plotted. LongMemEval is a 500-question long-term memory benchmark (Wu et al., 2024); we score its 470 non-abstention questions.
LongMemEval R@5 · 13.0 store mode
recall_any@5 by question type · retrieval, not answer accuracy
Not plotted — published on a different metric:
mem0 · answer accuracySupermemory · answer accuracyZep · DMR benchmark
Search latency
warm = caches hot · cold = first query after start
warm p50 · eval 2026-04-17 0.065 ms
warm p95 · eval 2026-04-17 2.97 ms
LoCoMo query p50 · 13.x 18.2 ms
cold p50 · eval 2026-04-17 1,333 ms
Warm rows are cached steady-state queries; the LoCoMo row is full hybrid retrieval. Sources:
evals/results-2026-04-17.json,
benchmarks/results/v13-locomo-retrieval.json.
Zero LLM calls and zero network requests on the default save/search path — enforced by
tests/test_no_llm_hot_path_v11.py.
Limits we state for 14.x
- No top-10 ranking and no new default answer-quality improvement is claimed.
- LoCoMo 66.49% and LongMemEval 73.20% are controlled development QA measurements, not independent evaluations.
- Against Mem0 OSS on LoCoMo with the same prompt and judge, the paired difference was +0.84 pp, 95% CI [−3.03; +4.96]: no quality advantage is established.
- The optional BGE reranker at one thread measured p95 ≈ 2,179 ms on Linux ARM64 — above the 200 ms target.
- An earlier comparison of our retrieval recall with a competitor's answer accuracy was invalid and has been withdrawn.
Sources: docs/RELEASE_V14.md · docs/LOCOMO_V14_RESULTS.md · release verification report
Found a wrong number? Open an issue with a link to the source and we will re-run our eval and correct this page. file an issue →
vs everyone else
Honest comparison. No mixed metrics.
This table compares architecture, not scores. Our published benchmarks measure retrieval recall; most projects here publish end-to-end answer accuracy with their own generator and judge, and the two cannot share a column. One-on-one pages: vs Mem0, vs agentmemory, vs mcp-memory-service, vs Claude Code's built-in memory.
| Project | LLM in hot path | Self-host | Deps | Notes |
|---|---|---|---|---|
| total-agent-memory | no | yes | SQLite + FastEmbed | publishes retrieval recall, reproducible without an API key · MIT |
| agentmemory (iii) | no | yes | iii engine (ELv2, pre-1.0) | benchmark figures are self-reported in its README |
| Letta / MemGPT | yes | optional | Postgres + vector DB | agent runtime · LLM in hot path |
| mem0 | yes | optional | Qdrant / pgvector | publishes end-to-end answer accuracy with its own generator + judge — not comparable with retrieval recall |
| Zep | yes | optional | Postgres + Graphiti | graph-first memory layer |
| CLAUDE.md | no | yes | plain text | loads everything every turn · no retrieval |
Our only like-for-like quality comparison is a development run, not a held-out one: LoCoMo QA against Mem0 OSS with the same prompt and judge gave a paired difference of +0.84 pp, 95% CI [−3.03; +4.96] — no quality advantage is established (docs/LOCOMO_V14_RESULTS.md).
Spot something wrong? open an issue with a link to the source — we'll re-run our eval and update.
Agents & IDEs
Works with every coding agent you already use.
11 agents and IDEs supported out of the box. The npm wrapper writes the MCP entry into the config file each client actually reads and keeps everything else in it. No manual JSON. Hermes Agent gets a native memory provider plugin. Restart the client — memory is live.
Claude Code
Anthropic
Official Anthropic CLI. Capture hooks fire automatically on prompts, tool use and session end.
~/.claude.json $
npx -y total-agent-memory connect claude-code Claude Desktop
Anthropic
Anthropic's desktop app. The MCP entry goes into its own config; memory tools appear in every chat.
claude_desktop_config.json $
npx -y total-agent-memory connect claude-desktop Codex CLI
OpenAI
OpenAI Codex CLI. TOML config patched, MCP server wired in one command.
~/.codex/config.toml $
npx -y total-agent-memory connect codex Cursor
Cursor
AI-first IDE. Memory MCP appears in Cursor's server panel — works in chat and agent mode.
~/.cursor/mcp.json $
npx -y total-agent-memory connect cursor Cline
Cline
VSCode agent extension. Multi-turn plans use memory automatically once wired.
cline_mcp_settings.json (VS Code global storage) $
npx -y total-agent-memory connect cline Continue
Continue.dev
Open-source IDE assistant. Memory is exposed as a tool via the MCP block in config.
~/.continue/mcpServers/memory.yaml $
npx -y total-agent-memory connect continue Windsurf
Codeium
Codeium's agent-native IDE. Cascade picks up memory_recall automatically.
~/.codeium/windsurf/mcp_config.json $
npx -y total-agent-memory connect windsurf Gemini CLI
Google's open-source Gemini CLI. Memory drops in as a standard MCP server.
~/.gemini/settings.json $
npx -y total-agent-memory connect gemini-cli OpenCode
sst.dev
Open-source coding agent by sst. MCP-native — memory just works.
~/.config/opencode/opencode.json $
npx -y total-agent-memory connect opencode Hermes Agent
Nous Research
Memory provider plugin: saves each finished turn, recalls relevant records before the next one, adds tam_recall and tam_save. Local TAM or the team server.
memory.provider: tam $
hermes plugins install vbcherepanov/hermes-tam-memory#hermes_tam_memory Aider
Aider
Terminal AI pair-programmer without MCP support. Use the lookup-memory CLI side-by-side.
~/.aider.conf.yml $
lookup-memory --help Don't see your agent?
If it speaks MCP, it works. Point any MCP client at total-agent-memory (in ~/.tam/.venv/bin/) and you're done.
REST API
Also exposes a REST endpoint on :37737. Drive it from scripts, CI, or any agent SDK that prefers HTTP over MCP.
CLI tool
A standalone lookup-memory binary is installed alongside the server for shell scripts and sub-agents.
Wire your IDE
One command per editor.
The npm CLI writes the MCP server entry into your IDE's config and merges with anything already there. No manual JSON editing.
- claude-code
- codex
- cursor
- cline
- continue
- aider
- windsurf
- gemini-cli
- opencode
- claude-desktop
- hermes
terminal
$ npx -y total-agent-memory connect claude-code
✓ Wired claude-code → ~/.claude.json
› Restart your IDE for the change to take effect.
$ npx -y total-agent-memory connect cursor
✓ Wired cursor → ~/.cursor/mcp.json
$ npx -y total-agent-memory connect codex
✓ Wired codex → ~/.codex/config.toml
$ npx -y total-agent-memory status
✓ python3 : Python 3.12.5
✓ uv : uv 0.8.17
✓ server : v14.9.0
✓ memory.db : 12.4 MB · 2,147 entriesFAQ
Questions you'd ask in an interview.
Is it really free?
Yes. MIT licence. No paid tier, no telemetry, no email signup. The server runs on your machine — or on your own server in team mode.
Does any data leave my machine?
Not by default. Memory lives in local SQLite files and FastEmbed computes embeddings locally. Internal LLM tasks are optional: with a local Ollama they stay on your machine; if you configure an OpenAI-compatible endpoint or Anthropic, that provider receives the content used in those tasks. Set MEMORY_LLM_ENABLED=false to keep everything on your own infrastructure.
Which Python version do I need?
Python 3.11 or newer. 14.0.0 states the real minimum: 13.x already imported tomllib and datetime.UTC, so it never actually ran on 3.10 despite declaring support. The release CI matrix covers Python 3.11, 3.12 and 3.13.
Why is this better than just using CLAUDE.md?
CLAUDE.md is loaded in full on every turn, so it grows with every note until it crowds the context window. total-agent-memory keeps records outside the prompt and retrieves only the ones relevant to the current request.
How does it compare to mem0 / Letta / Zep / Supermemory?
Two differences we can support. (1) The default hot path is LLM-free, so search spends no tokens. (2) We publish retrieval recall you can re-run without an API key, measured on 13.x: 0.607 R@5 on LoCoMo, 0.448 on BEAM at the 1M-token scale, 95.1% R@5 on LongMemEval. Competitors mostly publish end-to-end answer accuracy with their own generator and judge; recall and accuracy cannot be compared or subtracted. In a controlled development LoCoMo QA run with the same prompt, the paired difference against Mem0 OSS was +0.84 pp, 95% CI [−3.03; +4.96] — no quality advantage is established, and we claim no top-10 ranking.
Does it support team sharing?
Yes, since 14.0.0. One authenticated server holds personal, team and shared memory, each with its own database, graph and index. Team members are readers or editors, every change is attributed to the token owner with revision history, and IDEs connect through a lightweight remote MCP bridge. Local single-user mode is unchanged.
Does it work on Windows?
Yes. The npm wrapper handles venv creation on Windows, and the release CI matrix includes Windows 2022. Install via npx -y total-agent-memory; Python 3.11+ is required.
Are the benchmark numbers verifiable?
Yes. Each number links to a result file in the product repository — evals/longmemeval-2026-08-27-v13-store.json, benchmarks/results/v13-locomo-retrieval.json, benchmarks/results/v13-beam-1M.json — with runners under benchmarks/. Controlled development QA measurements and their limits are in docs/RELEASE_V14.md. If you can't reproduce a number, file an issue and we'll re-run.
Support the project
Self-funded. Local-first. No VC strings.
total-agent-memory is free, MIT, and stays that way. Every star, every link, and every one-time tip keeps it that way — and funds the next release.
⭐ Star on GitHub
free · 2 seconds
The single most useful thing you can do. Github stars feed every "trending memory MCP" list and ranking.
vbcherepanov/total-agent-memory →🤝 PayPal tip
one-time · any amount
Paid for embeddings models, paid for GPU bench runs, paid for the domain. Every tip directly funds the next release.
paypal.me/VitaliiCherepanov →𝕏 Share it
free · pre-filled
One retweet from someone in AI moves the needle more than a week of grinding. Tagged @vbcherepanov.
tweet a one-liner →No Stripe, no Patreon tier-system, no "premium memory features behind a paywall" — just a single PayPal link. If you'd rather invoice — email me.
Stop re-explaining yourself.
One command to install. Works with Claude Code, Cursor, Codex, Hermes Agent and 7 more.