Add Persistent Memory to Claude Code with MCP: A Step-by-Step Guide (2026)

Claude Code is sharp within a single session and amnesiac across them. Close the terminal, come back tomorrow, and the conventions you set, the decisions you made, and the context you carefully loaded are gone. The usual answer is a CLAUDE.md file, but that is static documentation you maintain by hand, not memory the agent forms and recalls on its own. This guide wires up real persistent memory through MCP, step by step.

Why Claude Code forgets, and why CLAUDE.md is not enough

Every Claude Code session starts from a clean context window. CLAUDE.md helps because it is auto-loaded, but it has two limits: you write and prune it by hand, and it is identical for every task, so it competes for context budget even when most of it is irrelevant to what you are doing right now. What you actually want is for the agent to record a fact once, recall only the relevant facts later, and let you inspect why it recalled them.

That record, recall, and lineage loop is what an MCP memory server adds.

Step 1: Install an MCP memory server

Claude Code speaks the Model Context Protocol, so any MCP-compatible memory server plugs in the same way. Using Memnode as the example, build and install the local server:

cargo build --release --manifest-path data-plane/Cargo.toml
memnode install-mcp --target claude-code --verify

The --verify flag drives the installed entry the way the MCP client will, so a wrong command path fails immediately instead of silently on first use. Then confirm the server is registered:

claude mcp list

Step 2: Teach it something worth remembering

Store a convention the agent will genuinely need again, not a throwaway sentence:

remember that this repo uses Zod for request validation in the route layer

Step 3: Recall it in a later session

Open a fresh session tomorrow and ask the way the question naturally comes up during real work:

what do we use to validate request payloads?

A good memory layer returns the fact plus enough provenance to trust it, not a fuzzy semantic approximation.

Step 4: Inspect lineage and correct

This is the part most memory tools skip: ask where a memory came from, and change it when the convention changes.

show lineage for that memory

When you later migrate off Zod, you correct the memory instead of hunting for a stale line in a growing CLAUDE.md. The old fact is superseded with a visible correction chain rather than silently lingering and misleading the agent months later.

When Claude Code memory is not working, check these first

• Server not registered. Run claude mcp list. If it is missing, the install did not write the MCP config; re-run install with --verify.
• Stale binary path. If you moved or rebuilt the binary, the registered command path no longer resolves. Re-install.
• Confusing CLAUDE.md with memory. Editing CLAUDE.md is not the MCP memory tool. Real memory is recorded through the agent, recalled across sessions, and inspectable.
• Local versus hosted scope. Local memory is per-machine. If you expect recall on another laptop or a CI agent, you need hosted memory: see Hosted vs Local Agent Memory.

Which memory server should you use?

Several MCP memory servers exist and they make different trade-offs on trust model, lineage, and hosting. We compare the main ones in MCP Memory Servers Compared, and if you want to watch the full record, recall, and lineage loop end to end, the Claude Code memory demo walks one repo convention through every step.

Next step

The install surface and config details live on the MCP install page. For agents beyond the editor, such as background jobs, multi-machine systems, and team-shared agents, the agents quickstart covers the hosted API.