Persistent memory for Claude Code

Claude Code starts every session with an empty context. It reads your CLAUDE.md files and its own auto memory notes, and that is all it knows about yesterday. This page sets up total-agent-memory (TAM) as an MCP memory server, so Claude can save decisions, fixes and facts and find them again by meaning, in any project.

What you need

• Claude Code, any recent version.
• Python 3.11 or newer on your PATH.
• About 2 GB of free disk for the program, the small embedding model it downloads once, and your database.

No API key, no account, no GPU. Nothing leaves your machine.

Step 1: install the plugin

Inside a Claude Code session, type:

/plugin marketplace add vbcherepanov/total-agent-memory
/plugin install total-agent-memory@vbcherepanov

This installs three things in one step:

• the MCP server, registered as memory;
• the memory-protocol skill, which tells Claude when to save and when to recall;
• capture hooks, which record session summaries and errors without you asking.

If you would rather use a terminal, one command does the same server registration:

npx -y total-agent-memory connect claude-code

Both paths put everything under ~/.tam/: a private Python environment, the database ~/.tam/memory.db, logs, and two background helpers (a local dashboard on http://127.0.0.1:37737 and a reflection worker). Add --no-services to the terminal command if you do not want the helpers.

Step 2: check the connection

Restart Claude Code and type /mcp. You should see memory listed as connected. If it is not, open Troubleshooting.

Step 3: save and recall something

Say to Claude:

Remember that our staging database is on port 5433.

Claude calls memory_save. Now start a new session, in the same project or another one, and ask:

Which port is staging on?

Claude calls memory_recall and answers from memory. You never type a tool name; the skill tells Claude which one to use.

What gets saved, and when

With the skill installed, Claude saves on its own at these moments:

• Decisions with the reason behind them: “chose pgvector over Chroma because we need row-level security”.
• Solutions to bugs: the error, the root cause and the fix.
• Facts about the project: ports, hosts, conventions, who owns what.
• Session summaries at the end of a session, with next steps and pitfalls, which the next session reads first.

You can also ask for anything explicitly: “remember this”, “what did we decide about X”, “what went wrong last time”.

How it fits with CLAUDE.md and auto memory

Keep using both. CLAUDE.md is for instructions: build commands, coding rules, project layout. Auto memory holds Claude’s own short notes per repository. TAM holds knowledge across every repository and every tool: it is searched by meaning, records have types and dates, and Cursor or Codex CLI see the same memory. The differences are laid out in vs Claude Code’s built-in memory.

Where the data is

One SQLite file: ~/.tam/memory.db. Back it up by copying it. Delete it and the memory is gone. Nothing is sent anywhere: the save and search paths make no network call and no model call, which the test suite checks on every release. Optional enrichment with a local Ollama or a hosted model is off by default; see Privacy and local-first.

Next

• Build the habits that make memory useful: Your first day.
• Connect a second tool to the same memory: Quick start.
• Set up memory for a team: Team server.