How to give Claude Code memory between sessions

Claude Code doesn't remember your last session: each one starts with a fresh context window. Three things carry knowledge over. CLAUDE.md holds the instructions you write. Auto memory holds notes Claude writes for itself on your machine. A shared ledger over MCP, such as RepoMemory, holds the decisions, lessons and tasks that every agent and teammate on the project should see. Use the first two for how to work in the repository, and the third for what has happened in it.

What Claude Code carries over by itself

Anthropic's memory docs (checked on 30 October 2026) describe two mechanisms, both loaded at the start of every session:

Both are context, not enforced rules. The docs suggest keeping each CLAUDE.md under about 200 lines, because longer files cost context and are followed less reliably.

Where they stop

• Auto memory stays on one machine. It isn't shared across machines, cloud sessions or teammates. A lesson Claude learned on your laptop doesn't reach the CI agent or a colleague's Cursor.
• CLAUDE.md is for rules, not history. "We reverted the checkout captcha because orders fell 5%" is worth knowing before anyone touches checkout, but a file loaded whole into every session can't hold every such story without growing past the size where it is followed.
• Nothing is retired. When a decision changes, someone has to find and edit the old line, or the file says both things.
• Only Claude Code reads auto memory. Codex, Cursor and other agents working on the same repository don't see it.

Add a shared ledger over MCP

RepoMemory is an MCP server that keeps a project's decisions, lessons, guardrails, notes and tasks. Claude Code calls brief at the start of a session, recall before a change, and record_entry when something is worth keeping. Recall searches, so only the entries about the change at hand come back, and the ledger can grow without filling the context.

1. Create a free key on the API keys page and add the server:

   claude mcp add --transport http repomemory https://api.repomemory.dev/mcp \
     --header "X-API-Key: $REPOMEMORY_KEY"
   

2. Add this to the repository's CLAUDE.md or AGENTS.md, so every session knows the project's ledger and when to use it:

   ## Project memory (RepoMemory, project "acme/shop")
   - At the start of a session, call `brief` for the project: it returns every guardrail, the open tasks and the latest decisions. Never break a guardrail.
   - Before planning a change, removing code that looks unneeded or retrying an approach, call `recall` with words about the change. Follow what it returns.
   - When a change is reverted, a fix took real digging, or you choose one approach over another, call `record_entry` (kind lesson or decision) saying what happened, why, and what to do instead, with your name in `agent`.
   

3. Or do both at once in the repository with the command line tool (Node.js 22 or newer):

   export REPOMEMORY_KEY=sk_live_...
   npx @plexsicity/repomemory init
   

The next session starts with a call like this one, made for you by Claude:

curl -s https://api.repomemory.dev/v1/brief \
  -H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
  -d '{"project":"acme/shop"}'

It returns every active guardrail in full, the open tasks and the newest decisions and lessons, so the session begins where the last one stopped.

What to keep where

• CLAUDE.md: how to build and test, conventions, the project's ledger name.
• Auto memory: your own preferences, which nobody else needs.
• The ledger: why something is the way it is, what was tried and reverted, rules nobody should break, and tasks other agents may pick up.

Limits to know

Recall matches words, not meaning: "captcha checkout" finds a lesson titled "Captcha on checkout", while "why did orders drop" may not. Agents only record what they are told to, which is what the CLAUDE.md lines are for. RepoMemory is hosted only. The free plan allows 300 new entries a month; recall, claims and retires are free. See pricing and the docs for other clients.