Persistent, local memory for AI coding agents: Claude Code, Codex CLI, Cursor and any MCP client. Website and documentation: totalmemory.dev · Quick start · Claude Code guide · Benchmarks · Compare with other tools total-agent-memory (TAM) is an open-source memory server for AI coding agents. Coding agents start every session without memory of earlier ones, so decisions, fixes and project conventions have to be…
total-agent-memory (TAM) is an open-source memory server for AI coding agents.
Coding agents start every session without memory of earlier ones, so decisions,
fixes and project conventions have to be explained again. TAM stores decisions,
solutions, facts, errors and session summaries on your machine and returns them
through the Model Context Protocol (MCP), so
any MCP client can use it without code changes.
Each store is one directory built around a SQLite database. Recall combines
full-text BM25, dense embeddings computed locally, fuzzy matching and a
knowledge graph, and fuses the ranked lists with reciprocal rank fusion. A local
cross-encoder then reranks the result: by default it starts as soon as its model
has loaded in the background, and MEMORY_CROSS_RERANK=off turns it off. The
default profile makes no LLM call on write or search, so retrieval can be
measured offline. With the cross-encoder off, reruns on fresh stores returned
the same ranking for every LoCoMo question. With the default setting the first
queries of a process can run before the model has loaded, so reruns are not
guaranteed to match. Facts can carry validity intervals (kg_add_fact, kg_at),
and a newer value of a single-valued fact can retire the older one.
TAM is for developers who use coding agents daily and for researchers who need
a memory baseline they can run locally, inspect and change. The same package
can also run as a team server: personal, department and company areas are
separate stores behind one gateway, with roles, authorship and an audit trail
(team server).
Installation
TAM needs Python 3.11 or newer. CI tests Python 3.11, 3.12 and 3.13 on
Ubuntu, Windows and macOS.
From PyPI (use a virtual environment, or pipx / uvx):
pip install total-agent-memory # or: pipx install total-agent-memory
uvx total-agent-memory # run once without installing
This installs the total-agent-memory (alias tam) MCP server and the
tam-team, tam-remote and lookup-memory commands. The default cross-encoder
runs on ONNX through fastembed and needs no extra. A separate
sentence-transformers reranker pulls in PyTorch and is an extra:
pip install "total-agent-memory[rerank]". The PostgreSQL backend of the team
server is the [postgres] extra.
Register it with your clients. Run tam setup at a terminal. The wizard
asks “Just me” or “Company server”, detects Claude Code, Claude Desktop, Codex,
Cursor, Windsurf, Gemini CLI, Cline and OpenCode, and registers the server with
the ones you pick (setup wizard).
First start. With no command, tam starts the MCP server on stdio, which
is how MCP clients run it. tam --help lists the commands and tam --version
prints the version (from 14.11; earlier versions start the server for any
argument, so use tam setup --help there). The first start downloads about
330 MB of models: the text embedder (about 240 MB) and the cross-encoder (about
90 MB). The cross-encoder loads in the background, so a short script that exits
after a few queries gets the fused order without it. fastembed keeps the models
in the system temp directory, which macOS clears from time to time; set
TAM_MODEL_CACHE=~/.tam/models to keep them.
Other channels:
Channel
Command
Docker (linux/amd64, linux/arm64)
docker run -p 127.0.0.1:3737:3737 -p 127.0.0.1:37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.10.0 — MCP over HTTP on :3737/mcp, dashboard on :37737; both need the token in ~/.tam/state/http-token (Authorization: Bearer, dashboard: open /login#token=..., the token stays in the URL fragment and is exchanged for an opaque session cookie)
Use one of the two Claude Code plugins, not both. Per-platform details, WSL2,
the IDE matrix, uninstalling and troubleshooting are in the
installation guide.
Quick start
Install the package and run tam setup, or add the server to your client by
hand. For Claude Code:
If you installed into a virtual environment, use the full path to its
total-agent-memory executable.
Restart the client. Memory is stored in ~/.tam/ unless TAM_MEMORY_DIR
points elsewhere.
Ask the agent to remember something (“remember that we chose PostgreSQL
for billing because of row-level security”). It calls memory_save. In a
later session, ask “which database did we choose for billing?”; it calls
memory_recall and gets the record back.
To try the server without an agent, this script starts it over stdio with the
MCP Python SDK (installed as a dependency), saves one record and recalls it.
The SDK passes only a few variables to the server by default, so the script
hands over the full environment, including TAM_MEMORY_DIR:
import asyncio
import os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main() -> None:
server = StdioServerParameters(command="total-agent-memory", env=dict(os.environ))
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
await session.call_tool("memory_save", {
"type": "decision",
"content": "Chose PostgreSQL over MySQL for the billing service",
"context": "WHY: row-level security per tenant",
"project": "demo",
})
result = await session.call_tool("memory_recall", {
"query": "which database for billing", "project": "demo", "limit": 3,
})
print(result.content[0].text)
asyncio.run(main())
The first run downloads the default embedding model. The output
is JSON with the saved decision under results.decision. More examples:
tools and interfaces.
Running the tests
The tests run from a source checkout. These commands mirror the CI workflows
in .github/workflows:
git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
python3 -m venv .venv
.venv/bin/pip install -e . -r requirements-dev.txt
export FASTEMBED_CACHE_PATH="$PWD/.tam-models" TAM_MEMORY_DIR="$PWD/.tam-test-memory"
.venv/bin/python tests/smoke/prewarm_models.py # downloads the text and code embedding models and the cross-encoder (~940 MB) once
.venv/bin/python -m pytest tests -q
The tests need no API keys and no LLM; the full suite takes 15 to 20 minutes
on a laptop. Do not set MEMORY_LLM_ENABLED=false for the full suite: the
configuration tests check LLM auto-detection. Tests that need services you do not
have are skipped:
PostgreSQL (team server backend): install the extra with
.venv/bin/pip install -e ".[postgres]", then run
.venv/bin/python -m pytest tests -m postgres --backend=postgres or
--backend=both. Without TAM_TEST_PG_URL the fixtures start a pgvector
container through Docker. See CONTRIBUTING.md and
.github/workflows/postgres.yml.
Installed-package smoke test: python tests/smoke/installed_runtime.py
checks an installed wheel over local and remote MCP.
Reproducing the benchmarks
The retrieval benchmarks (LoCoMo, LongMemEval, BEAM) need no API key and run
with scripts in benchmarks/ once the public datasets are
downloaded. The table below was measured on v13.0.0, before the cross-encoder
became the default in 14.5, so it describes retrieval without the cross-encoder
and not a default install of the current version:
Benchmark
Metric
Result
LongMemEval (470 questions)
R@5 (recall_any)
95.1%
LoCoMo (1,536 questions)
R@5
0.607
BEAM, 1M-token scale (625 probes)
R@5
0.448
Default settings score higher on LoCoMo and take much longer per query. In the
JOSS review of
v14.6.0 the editor measured R@5 of about 0.745 at about 495 ms median with the
defaults, against 0.607 at about 18 ms with MEMORY_CROSS_RERANK=off. Our own
runs of v14.6.0, three on a fresh store per setting, gave R@5 0.611 with the
cross-encoder off and 0.746 with the default and with on, at about 0.95-1.0 s
median per query on an Apple M2 Max; the median depends on the CPU. Each setting
returned the same ranking for every question in all three runs. With the default,
the first query of a process can arrive before the cross-encoder has loaded and
keeps the fused order; in these runs that changed one question out of 1,986
(rows, reports and commands).
Dataset locations, commands, end-to-end (LLM-judged) accuracy, negative
controls, latency and the 14.x studies are in
docs/benchmarks.md.
Documentation
Installation guide: all channels, per-platform setup, WSL2, IDE matrix, troubleshooting
Setup wizard: tam setup and the team server’s web wizard
A paper describing TAM is under review at the Journal of Open Source Software
(paper/paper.md). Until it is published, please cite the
software and the preprint:
Citation metadata for the software is in CITATION.cff.
Contributing
Issues, pull requests and benchmark reproductions are welcome. See
CONTRIBUTING.md for the development setup, the rules for a
pull request and the commit convention. Report security issues privately as
described in SECURITY.md.
Donations to support development: PayPal.
评论