vbcherepanov/total-agent-memory

>
> 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; an
optional cross-encoder can rerank the result. The default profile makes no LLM
call on write or search, so retrieval can be measured offline and a rerun gives
the same result. 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):
This installs the total-agent-memory (alias tam) MCP server and the
tam-team, tam-remote and lookup-memory commands. The optional
cross-encoder 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).
**Other channels:**
| Channel | Command |
|---|---|
| Docker (linux/amd64, linux/arm64) | docker run -p 3737:3737 -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.9.0 — MCP over HTTP on :3737/mcp, dashboard on :37737 |
| npx connector | npx -y total-agent-memory connect claude-code (or codex, cursor, cline, continue, aider, windsurf, gemini-cli, opencode) |
| Claude Code plugin (server, skill and capture hooks) | /plugin marketplace add vbcherepanov/total-agent-memory /plugin install total-agent-memory@vbcherepanov |
| Plugin for Claude Code and Cowork, from the plugin repository (server and skill, no hooks; needs uv) | /plugin marketplace add vbcherepanov/total-agent-memory-plugin /plugin install total-agent-memory@vbcherepanov |
| The same plugin for Codex CLI | codex plugin marketplace add vbcherepanov/total-agent-memory-plugin codex plugin add total-agent-memory@vbcherepanov |
| Source checkout with IDE hooks and background services | git clone https://github.com/vbcherepanov/total-agent-memory.git && cd total-agent-memory && ./install.sh --ide claude-code (Windows: install.ps1 -Ide claude-code) |
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.