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

... View full README on GitHub