Claude Code starts every session with a fresh context window. Two built-in mechanisms carry knowledge across sessions — CLAUDE.md files (instructions you write) and auto memory (notes Claude writes itself) — and for knowledge that must transfer across tools, models, or machines, an external memory layer connected via the Model Context Protocol (MCP) extends memory beyond a single tool. The right approach depends on what you need to persist: stable instructions, learned corrections, or cross-tool knowledge that follows you from Claude Code to Cursor to the terminal.
You correct Claude Code’s testing approach on Monday. On Tuesday, it makes the same mistake. You explain your database schema in one project; that night, in another session, Claude has no idea. Each session begins blank — the context window resets, and everything you taught it is gone.
This is not a bug. It is the fundamental constraint of context-window-based AI: the model has no persistent state between sessions. The fix is to externalize memory — write down what Claude should know, or let Claude write it down itself, so knowledge survives the session boundary.
Claude Code provides two built-in mechanisms for this, and the Model Context Protocol (MCP) extends memory beyond Claude Code itself.
CLAUDE.md is a markdown file you write that gives Claude persistent instructions for a project. Claude reads it at the start of every session, so anything in CLAUDE.md is available immediately without re-explaining (code.claude.com/docs/en/memory).
CLAUDE.md files can live in several locations, each with a different scope:
| Scope | Location | Shared with |
|---|---|---|
| User | ~/.claude/CLAUDE.md | Just you (all projects) |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team via version control |
| Local | ./CLAUDE.local.md | Just you (current project, gitignored) |
| Managed policy | OS-level path (e.g. /etc/claude-code/CLAUDE.md) | All users on the machine |
Claude walks up the directory tree from your working directory, loading CLAUDE.md files at each level. All discovered files are concatenated into context — they do not override each other. A project CLAUDE.md appears in context after a user CLAUDE.md, so project instructions take priority.
Treat CLAUDE.md as the place you write down what you would otherwise re-explain. Add to it when:
Keep it to facts Claude should hold in every session: build commands, conventions, project layout, “always do X” rules. Target under 200 lines — longer files consume more context and reduce adherence. Use specific, verifiable instructions (“Use 2-space indentation” rather than “Format code properly”).
For larger projects, .claude/rules/ lets you scope instructions to specific file types or directories. A rule with frontmatter paths: ["src/api/**/*.ts"] only loads when Claude works with matching files, reducing noise and saving context.
The /init command analyzes your codebase and generates a starting CLAUDE.md automatically — build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.
Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits. It decides what is worth remembering based on whether the information would be useful in a future conversation (code.claude.com/docs/en/memory).
Auto memory requires Claude Code v2.1.59 or later. It is on by default.
Each project gets its own memory directory at ~/.claude/projects/<project>/memory/. The directory contains a MEMORY.md entrypoint and optional topic files:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Concise index, loaded into every session
├── debugging.md # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ... # Any other topic files Claude createsThe first 200 lines of MEMORY.md (or 25KB, whichever comes first) are loaded at the start of every conversation. Claude keeps MEMORY.md concise by moving detailed notes into separate topic files, which it reads on demand using its standard file tools.
Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments.
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it contains | Instructions and rules | Learnings and patterns |
| Scope | Project, user, or org | Per repository |
| Loaded into | Every session (full file) | Every session (first 200 lines / 25KB) |
| Use for | Coding standards, workflows, architecture | Build commands, debugging insights, preferences Claude discovers |
They are complementary. Use CLAUDE.md when you want to guide Claude’s behavior with explicit rules. Use auto memory when you want Claude to learn from your corrections without manual effort. Run /memory in a session to browse and edit both.
Claude Code’s built-in memory is powerful but has structural limits:
The Model Context Protocol (MCP) is an open protocol — JSON-RPC 2.0 based, inspired by the Language Server Protocol — that standardizes how LLM applications connect to external data sources and tools (modelcontextprotocol.io/specification/2025-11-25). It is transport-level: it defines how an agent talks to a memory server, not what format the memories are in.
MCP makes external memory practical for Claude Code because Claude Code is an MCP client. Any MCP-compatible memory server can be connected, giving Claude Code access to a memory layer that persists across sessions, across projects, and — critically — across tools.
| Property | Built-in (CLAUDE.md + auto memory) | MCP memory server |
|---|---|---|
| Cross-tool | Claude Code only | Any MCP client (Claude Code, Cursor, Windsurf, OpenClaw) |
| Cross-project | Per-repository | Global or scoped by domain |
| Semantic recall | No (full load or on-demand file read) | Yes (BM25 + embeddings) |
| Feedback loop | No | Varies by system (some support relevance rating) |
| Decay | No | Varies by system (some implement ACT-R activation decay) |
| Format | Markdown files | Varies (vectors, knowledge graphs, plain-text engrams) |
| Transport | Filesystem | MCP (JSON-RPC 2.0) |
Several MCP-compatible memory servers exist, each with different storage formats and design philosophies:
PLUR (Apache-2.0, ~217 stars, github.com/plur-ai/plur) stores memory as plain-text YAML engrams — human-readable files you can inspect, edit, and version-control. Setup is one command: npx @plur-ai/mcp init creates ~/.plur/ for storage, adds PLUR to your .mcp.json, and installs Claude Code hooks for automatic engram injection. The hooks auto-close the memory lifecycle: a SessionEnd hook captures a closing episode and cleans up session state. Memory includes activation decay (ACT-R model), feedback signals, and hierarchical scoping. Search is fully local: BM25 + BGE embeddings + Reciprocal Rank Fusion, zero API calls.
Mem0 (Apache-2.0, ~60.5K stars, github.com/mem0ai/mem0) provides a memory layer with vector + graph storage and a CRUD API. The official OpenMemory MCP server connects Mem0 to Claude Code. Memory is stored as vector embeddings with entity linking — not human-readable files, but the API is straightforward. Mem0’s benchmarks report 92.5 on LoCoMo and 94.4 on LongMemEval (arXiv:2504.19413).
Graphiti/Zep (Apache-2.0, ~28.6K stars, github.com/getzep/graphiti) builds real-time temporal knowledge graphs for agents. The Graphiti MCP server connects it to Claude Code. Memory is stored as graph edges with temporal validity windows — useful for tracking how facts change over time.
Official MCP memory server (@modelcontextprotocol/server-memory) provides a basic knowledge graph that Claude Code can read and write. It is a reference implementation — simpler than Mem0 or Graphiti, but useful for getting started with MCP-based memory.
To add an MCP server to Claude Code, add it to your .mcp.json (project-level) or ~/.claude/.mcp.json (user-level):
{
"mcpServers": {
"plur": {
"command": "npx",
"args": ["@plur-ai/mcp", "serve"]
}
}
}Or use the provider’s setup tool — PLUR’s npx @plur-ai/mcp init configures everything automatically, including hooks for automatic injection at session start and episode capture at session end.
Once configured, the MCP server’s tools are available to Claude Code. You can ask Claude to “remember that we use blue-green deploys” or “what did I tell you about the database?” and it will use the memory server’s tools to store and retrieve.
Start with CLAUDE.md. It is built in, requires no setup, and handles the most common need: giving Claude stable instructions for your project. Run /init to bootstrap, then refine.
Enable auto memory (it is on by default in v2.1.59+). Let Claude learn from your corrections without manual effort. Check it periodically with /memory.
Add an MCP memory server when:
The built-in mechanisms and an MCP server are not either/or. A practical setup: CLAUDE.md for project rules, auto memory for Claude’s own notes, and an MCP memory server for cross-tool, semantically searchable knowledge that follows you everywhere.
How do I add persistent memory to Claude Code? Two built-in mechanisms: CLAUDE.md files (instructions you write, loaded every session) and auto memory (notes Claude writes itself, v2.1.59+). For cross-tool or semantically searchable memory, connect an MCP memory server by adding it to .mcp.json. Run /memory in a session to view and edit all memory sources.
What is CLAUDE.md? A markdown file that gives Claude Code persistent instructions for a project. Claude reads it at the start of every session. Place it at ./CLAUDE.md (project, shared via version control), ~/.claude/CLAUDE.md (user, all projects), or ./CLAUDE.local.md (personal, gitignored). Run /init to generate one automatically from your codebase.
What is Claude Code auto memory? A feature (v2.1.59+) where Claude saves notes for itself across sessions — build commands, debugging insights, preferences. Stored as markdown in ~/.claude/projects/<project>/memory/. The first 200 lines of MEMORY.md are loaded every session. It is on by default and machine-local.
Can Claude Code memory transfer to Cursor or other tools? Built-in memory (CLAUDE.md, auto memory) is Claude Code-specific. To transfer memory across tools, use an MCP memory server — any MCP-compatible agent can connect to the same server. PLUR, Mem0, and Graphiti all provide MCP servers that work with Claude Code and other tools. See Tools for Giving Coding Assistants Persistent Memory for the broader tool landscape across Claude Code, Cursor, Windsurf, and Copilot.
How do I make Claude Code remember across sessions? Write stable instructions in CLAUDE.md. Enable auto memory so Claude takes its own notes. For knowledge that must transfer across tools or projects, add an MCP memory server to .mcp.json.
What is the MCP memory server? The Model Context Protocol (specification 2025-11-25, modelcontextprotocol.io) is an open protocol that standardizes how LLM applications connect to external tools and data sources. An MCP memory server exposes memory operations (store, recall, search) as MCP tools that Claude Code can call. The official @modelcontextprotocol/server-memory provides a basic knowledge graph; PLUR, Mem0, and Graphiti provide more advanced servers.