total-agent-memory

Purpose

total-agent-memory (TAM) is an open-source memory server for AI coding agents, with a target community that includes Claude Code, Codex CLI, Cursor, and any MCP client. Coding agents start each session without memory of previous sessions, so decisions, fixes, and project conventions often need to be restated. TAM stores decisions, solutions, facts, errors, and session summaries locally on the user's machine and returns them via the Model Context Protocol (MCP), so any MCP client can use it without code changes.

Main capabilities

• Local persistent memory: Each store is a directory built around a SQLite database, with data kept locally.
• Hybrid retrieval: Recall combines full-text BM25, locally computed dense embeddings, fuzzy matching, and a knowledge graph, and uses reciprocal rank fusion to fuse multiple ranked lists; an optional cross-encoder can rerank the results.
• No LLM calls by default: The default configuration makes no LLM calls when writing or searching, so retrieval results can be measured offline and repeated runs produce the same results.
• Temporal knowledge graph and fact invalidation: Facts can carry validity intervals (kg_add_fact, kg_at), and a newer value for a single-valued fact can invalidate the old value.
• Procedural memory and episodic memory: The project description supports procedural memory, episodic memory, AST codebase ingestion, and cross-project analogies.
• Team server mode: The same package can also run as a team server, where personal, department, and company zones are different stores behind the same gateway, with roles, authorship, and audit trails (team server).
• Tools and interfaces: The project description provides 74 MCP tools, a CLI, a TypeScript SDK, and a dashboard (other materials say 79 MCP tools; the project's actual version prevails).

Usage

TAM requires Python 3.11 or higher. CI tests Python 3.11, 3.12, and 3.13 on Ubuntu, Windows, and macOS.

Installation

Install from PyPI (a virtual environment is recommended, or pipx / uvx):

pip install total-agent-memory

This installs the total-agent-memory (alias tam) MCP server, as well as the tam-team, tam-remote, and lookup-memory commands. The optional cross-encoder reranker brings in PyTorch and is installed as an extra dependency:

pip install "total-agent-memory[rerank]"

The team server's PostgreSQL backend is the [postgres] extra dependency.

Registering with clients

Run in the terminal tam setup. 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 client chosen by the user.

You can also add the server manually. Claude Code:

claude mcp add memory -- total-agent-memory

For clients that use an mcpServers file:

{ "mcpServers": { "memory": { "command": "total-agent-memory" } } }

If installed into a virtual environment, use the full path to its total-agent-memory executable.

After restarting the client, memory is stored by default in ~/.tam/, unless TAM_MEMORY_DIR Point to other locations.

Basic usage

Have the agent remember something (for example, "remember that we chose PostgreSQL for billing because of row-level security"), and it will call memory_save. In a later session, ask "which database did we choose for billing?", and it will call memory_recall and retrieve the record.

The project also provides an example script that does not depend on an agent: start the server via stdio, use the MCP Python SDK to save a record and recall it; the first run will download the default embedding model, the output is JSON, and the saved decision is located at results.decision. For more examples, see "Tools and interfaces".

Testing and benchmarks

Tests run from a source checkout and do not require an API key or an LLM; the full suite takes about 15 to 20 minutes on a laptop. Tests related to services that are required but not installed will be skipped:

• PostgreSQL (team server backend): install pip install -e ".[postgres]", then run python -m pytest tests -m postgres --backend=postgres or --backend=both. When TAM_TEST_PG_URL is not set, the fixture will start a pgvector container via Docker.
• Browser tests (tests/browser, Playwright with Chromium, Firefox, WebKit) run in the image built by docker/Dockerfile.browser.
• Installed package smoke test:python tests/smoke/installed_runtime.py checks the installed wheel via local and remote MCP.

Retrieval benchmarks (LoCoMo, LongMemEval, BEAM) do not require an API key; after downloading the public datasets, run them using the scripts in benchmarks/. According to the project's own description, with the default configuration and v13.0.0, the results are: LongMemEval R@5 95.1%, LoCoMo 0.607, BEAM 1M 0.448. Other materials mention 74 MCP tools, 9 IDEs, and 100% local.

Applicable scenarios

• Developers who use coding agents daily and want the agent to remember decisions, fixes, and project conventions across sessions.
• Researchers who need a memory baseline that can run locally, be inspected, and be modified.
• Teams that need unified management of personal, department, and company memory zones (team server mode).

Limitations and notes

• Requires Python 3.11 or later.
• The default configuration does not call an LLM; the optional cross-encoder reranker and PostgreSQL team backend require additional dependencies.
• Benchmark results come from the project's own description (default configuration, v13.0.0); actual results may vary by version, configuration, and dataset; some performance details, latency, and end-to-end accuracy are in the project documentation.
• Some features (such as procedural memory, AST codebase ingestion, and cross-project analogy) are only mentioned by name in the provided materials, with no specific usage steps, effects, or limitations given.
• Fees, pricing, platform support details, specific usage steps, etc. are not explained in the provided materials.

Other information

• Website and documentation: totalmemory.dev.
• License: MIT. For third-party licenses, see THIRD-PARTY-LICENSES.md.
• The paper describing TAM is under review at the Journal of Open Source Software.
• For the security policy, contribution guidelines, changelog, roadmap, etc., see the corresponding files in the project repository.