LEARN

CLAUDE.md vs a memory MCP server: what actually goes where

Put stable facts a human curates in CLAUDE.md — it loads every session. Put decisions and dead ends an agent accumulates in a memory MCP server — it loads nothing until the agent searches. The test: would you open the file and type this by hand? If no, it belongs in the store.

Disclosure: we build the Kireo memory MCP server, which shows up once at the end. The framework below is the one we use to decide what goes in a markdown file and what goes in a store, and it holds whichever store you pick. Every competing product mentioned is linked with the date we checked it.

Short answer

You are not choosing between them. They are different layers and they coexist. The failure mode is putting facts in the wrong one: rules that must apply every single time end up behind a search that may not run, and a year of accumulated context ends up crammed into a file that gets loaded in full whether today's task needs it or not.

Anthropic's own documentation already draws this line. Its comparison table lists CLAUDE.md as written by you, containing instructions and rules, scoped to project, user or org; and auto memory as written by Claude, containing learnings and patterns, scoped per repository. We did not invent that split, and this page will not pretend otherwise. What the official framing does not answer is the next question — when a third layer is worth adding, and when it plainly is not.

Table wording quoted from code.claude.com/docs/en/memory, verified 2026-08-03.

The test that decides: who writes it, and how often it changes

Two questions settle almost every case. Who writes it? If a human types it, it is instruction. If it falls out of doing the work, it is memory. How often does it change? Instructions drift on the order of once a month. Memory accrues every session.

"Run pnpm --filter api test. The API talks to Postgres and Redis. Do not touch generated/." You typed those; you will re-read them when they go stale. That is a file.

"Tried batching the embedding upload at 500 symbols per request — the embedding service chokes on batches that large, so it is capped at 100." Nobody hand-edits that into CLAUDE.md. An agent hit it on Tuesday, and by Thursday, in a fresh session, it is gone unless something wrote it down. That is a store.

So: would I open the file and type this by hand? If yes, it is a CLAUDE.md fact. If it is a by-product — a decision, a dead end, a "we tried X and it broke Y" — it wants a store, because you are never going back to curate it into markdown.

The four layers, side by side

Most people already have two or three of these. The column that matters most is when it enters context, because that is the one you pay for on every single request.

Layer	Who writes it	When it enters context	Scope
CLAUDE.md / AGENTS.md	You, by hand	Every session, in full. Imported files load at launch too, so an @import organises but does not save context.	Managed policy, user, project or local. The project file ships in git.
Claude Code auto memory	Claude, while working	The MEMORY.md index loads at session start (first 200 lines or 25 KB, whichever comes first). Topic files are read on demand.	One git repository, shared across its worktrees. Machine-local.
Cursor Rules	You, by hand (.mdc files)	Four modes: always, when the agent judges it relevant, on a file-pattern match, or when @-mentioned.	Project, user, or the whole organisation on Team and Enterprise plans.
Memory MCP server	The agent, through a tool call	Only when the agent runs a search. If it never searches, the cost is zero.	Any MCP client, any machine you configure, plus shared namespaces.

Rows 1–2 from code.claude.com/docs/en/memory; row 3 from cursor.com/docs/context/rules; both verified 2026-08-03. Row 4 describes the Kireo memory MCP server, read from packages/mcp-server/src/tools/ at version 0.2.1.

"But Claude Code already has auto memory"

It does, it is on by default, and it is genuinely good. It stores a MEMORY.md index plus optional topic files such as debugging.md under ~/.claude/projects/<project>/memory/, and you can browse or switch it off with the /memory command. Before adding anything, understand its shape.

It has an on-demand tier — do not let anyone tell you otherwise. The MEMORY.md index loads at session start, but the docs are explicit that topic files "are not loaded at startup" and that Claude reads them with its standard file tools when it needs the information. The common claim that auto memory is "loaded, never queried" is simply wrong.
Retrieval is by path, not by meaning. The index points at a file; Claude opens it. That works well when your index is well organised, and less well when the thing you need was written under a heading you would not have thought to look under. A store ranks by similarity to the question instead.
It is selective by design. "Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation." That is the right default — you do not want every stray thought persisted — but it means the record is a subset of what happened, and you cannot recall what was never written.
It is machine-local, in the official wording: "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."

And the honest counter to our own argument: Anthropic ships an autoMemoryDirectory setting that relocates that directory to any absolute path. Point it at a synced folder and auto memory follows you between machines. If "one repo, several machines" is your whole problem, try that first — it costs nothing and adds no moving parts.

All quotes from code.claude.com/docs/en/memory, verified 2026-08-03.

You do not need a memory MCP server yet if…

We would rather you did not bolt on a server you have no use for. If all four of these hold, a well-kept file is enough and anything else is overhead.

One project, and one file still describes it. Anthropic's own advice is to "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." If you are comfortably under that, you do not have a volume problem to solve.
Your cross-tool need is only about static instructions. Then AGENTS.md already solves it, for free and with no server: an open format the project reports as used by over 60k open-source projects across 24+ platforms. Claude Code reads it through an @AGENTS.md import or a symlink, and its /init already picks up Cursor rules and Copilot instructions — with CLAUDE_CODE_NEW_INIT=1 it also reads AGENTS.md, .windsurf/rules/ and .clinerules.
One machine — or one you can sync. See autoMemoryDirectory above. A synced folder is a legitimate answer, and it is the officially supported one.
The team sharing you want is sharing of rules. A project CLAUDE.md in git already does that; Cursor pushes rules across an entire organisation from the dashboard on Team and Enterprise plans. Neither needs a memory layer.

If that is you, close this tab and go keep a good CLAUDE.md. Most solo, single-repo projects live here and there is nothing to fix.

Sources: code.claude.com/docs/en/memory, agents.md, cursor.com/docs/context/rules; all verified 2026-08-03.

When the file stops being enough

Four things move the needle. Note that each one is about the accumulated layer — the static layer really is a solved problem.

Two tools that both need the accumulated layer. You start a feature in Claude Code, then move to Cursor for the UI. AGENTS.md carries your rules across that boundary. Nothing in any file format carries "we tried X, it broke Y" from one tool's session history into the other's.
More than one machine, with no synced folder. Straight from the official docs quoted above: files are not shared across machines or cloud environments.
A team long tail. A committed CLAUDE.md shares the stable facts you all agreed to write down. The dead ends are precisely what a new teammate's agent would benefit from and precisely what nobody puts through code review.
Volume past hand-curation. Past a certain size the file is a wall of text loaded on every session whether or not a line of it is relevant today — and @imports do not help, because imported files load at launch as well.

Honest concession on that last point: both vendors already ship partial answers. Claude Code supports path-scoped rules in .claude/rules/ whose YAML frontmatter paths field makes them apply only when Claude touches matching files, and Cursor's "Apply to Specific Files" and "Apply Intelligently" modes do something similar. Both trigger on which files are in play, not on what your question means. That is the residual gap a searchable store fills — it is narrower than the pitch usually implies.

Cross-tool is a property of the protocol, not a product feature

This is the part vendors overclaim, so here is the plain version. MCP is "an open-source standard for connecting AI applications to external systems," and its own introduction offers the analogy: "Think of MCP like a USB-C port for AI applications." The specification is more direct still — it says MCP "takes some inspiration from the Language Server Protocol, which standardizes how to add support for programming languages across a whole ecosystem of development tools."

That is the whole mechanism. Hosts, clients and servers exchange JSON-RPC 2.0 messages against a published schema (current revision 2026-07-28), so a server written once is reachable from every conforming client. Any memory MCP server is cross-tool. It is not something a vendor built; it is something the vendor did not have to build. Several good ones exist, and it is worth knowing what each is better at:

mem0 / OpenMemory MCP — mem0 is Apache-2.0 with 62.4k GitHub stars, and OpenMemory MCP is "a private, local-first memory server" where "all memory is stored on your machine. Nothing goes to the cloud," exposing four tools and listing Cursor, Claude Desktop, Windsurf and Cline as compatible. If your hard requirement is that memory never leaves your laptop, this beats any hosted service including ours, by construction. (github.com/mem0ai/mem0, mem0.ai/blog/introducing-openmemory-mcp; star count and quotes verified 2026-08-03.)
Zep / Graphiti — Graphiti is "the open-source temporal context graph engine at the core of Zep's context infrastructure for AI agents," Apache-2.0, 29.5k stars, and it ships its own MCP server. Modelling memory as entities, relations and time-bounded validity answers questions that similarity search over text simply cannot — "what did we believe about this service in March, and what changed?" If your memory is really a graph, that is a stronger fit than any vector store. (github.com/getzep/graphiti, getzep.com; verified 2026-08-03.)
Letta — Apache-2.0, 24.1k stars, formerly MemGPT. Its memory blocks are "structured sections of the agent's context window that persist across all interactions" and are "always visible - no retrieval needed," with one block shareable by several agents. Note the layer difference: Letta is an MCP client and a platform for building stateful agents, not a memory server you attach to an editor. If you are building your own agent runtime, look at Letta before you look at any of us. (github.com/letta-ai/letta, docs.letta.com; verified 2026-08-03.)

The protocol also tells you what it will not do for you. The specification states that "while MCP itself cannot enforce these security principles at the protocol level, implementors SHOULD" build them in, and that hosts must obtain explicit user consent before invoking any tool. Openness buys connectivity, not governance. So the question to put to any memory server — ours included — is not "does it work with my editor," it is: can I see every memory it holds, edit it, export all of it, and delete it?

Protocol quotes from modelcontextprotocol.io/docs/getting-started/intro and modelcontextprotocol.io/specification/latest, both verified 2026-08-03. Star counts are single-point readings on that date and will drift.

The context budget, with real numbers

"A file is loaded, a store is queried" is the mechanical difference. Here is what that costs, measured on the repository this site is built from rather than asserted.

382,209tokens if you pasted in all 336 source files a code index would scan (1,371,357 bytes). Drop 17 generated design .jsx files and 319 files still come to 218,606 tokens. Both overflow a 200K context window.
43,626tokens for the 213 extracted code symbols (159,961 characters). Per symbol: median 106 tokens, mean 204.8, p90 428, largest 2,248.
~1,060–2,048tokens for one default retrieval of 10 results — median × 10 and mean × 10. Projected from the measured size distribution, not a measured live recall. Ten worst-case symbols would come to 14,851.

We are deliberately not turning that into a "saves you N×" headline. The two numbers are not measurements of the same thing — one is a hypothetical full paste, the other is a projection from a size distribution — and a ratio between them would be theatre. Read them as orders of magnitude: an always-loaded layer scales with the size of your project, a queried layer scales with the size of your question. That is the argument for keeping the always-loaded layer small, which is also why the official guidance puts CLAUDE.md under 200 lines.

Measured 2026-08-03 on this monorepo by running the same walk and tree-sitter extraction modules the kireo index CLI uses, three times with identical results. Token counts use OpenAI's tiktoken o200k_base encoding, not Claude's tokenizer — treat them as order-of-magnitude figures only.

If you decide you want the searchable layer

This is the only part of the page that is about our product. The Kireo memory MCP server is one implementation of the layer described above; everything in the framework applies just as well to the alternatives listed earlier. It is a stdio MCP server run through npx, so the config block is the same mcpServers shape most clients use. Node 20 or newer must be on PATH.

mcpServers config block

json

{ "mcpServers": { "kireo": { "type": "stdio", "command": "npx", "args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"], "env": { "KIREO_API_KEY": "ki_sk_xxx" } } } }

Claude Code has its own one-line CLI form instead of a JSON file — see the quickstart. Namespaces must match ^[a-z0-9_-]{1,32}$ and tags ^[a-z0-9_-]+$; no capitals, dots or slashes.

The eight tools your agent gets 8

Read from ALL_TOOLS in packages/mcp-server/src/tools/index.ts at version 0.2.1, in registration order. Only one of them spends context.

memory_save — Writes one memory. Requires content (1–8,000 characters); type, namespace, entities, tags, importance, occurred_at and metadata are optional.
memory_search — Hybrid search over your memories. Requires query; limit defaults to 10 and caps at 50. This is the only tool that pulls memories into context.
memory_recall — Lists a namespace without a query. limit defaults to 20 and caps at 50; order is recency or importance.
memory_get — Fetches one full record by id (the mem_… form).
memory_update — PATCH semantics — only the fields you pass change. Requires id plus at least one other field.
memory_delete — Soft delete. The record stays recoverable for 30 days, then is purged permanently.
memory_list_namespaces — Returns the namespace names and their creation times.
memory_health — Local server version, Node version and platform, plus the remote API status. The fastest way to tell "not installed" from "installed but not reachable".

On privacy, because it is always the next question: the published policy states that "your memory content and its embeddings stay on our own infrastructure (Hetzner compute)" and that "your memory text is never sent to a third-party AI or embedding provider." Every memory is readable, editable and deletable from the web dashboard, and exportable as JSON. Full text on the privacy page.

Three ways this decision goes wrong

Each of these is a consequence of the split itself, not of any one editor. All three are read out of the Kireo memory MCP server source at 0.2.1; equivalents exist in every retrieval-backed store.

1. Never put a must-always-apply rule behind retrieval

memory_search returns the top limit rows (default 10, max 50) ranked by a raw fusion score. The min_score argument is not an API parameter at all: the server applies it client-side (memory-search.ts:90-94) after the backend has already truncated to limit, so a filtered search can hand back fewer rows than you asked for. Ranking is a probability, not a guarantee. "Never commit directly to main" belongs in the file that always loads.

2. Recall by importance is not a ranking of your history

People reach for memory_recall with order: "importance" as a way to dump "everything that mattered" back out, as if it were a generated CLAUDE.md. It is not. That path pages through at most 1,000 recent records — 200 per page, five requests — sorts those locally, and always returns next_cursor: null (memory-recall.ts:56-73, 98). It answers "most important of the recent," and it cannot be paged past that.

3. Editing the file is instant; un-remembering is not

Fixing a wrong line in CLAUDE.md takes one keystroke and is local to you. A store has a retention model instead: memory_delete is soft delete only — the hard flag is accepted for compatibility and ignored — and the record stays recoverable for 30 days before it is purged (memory-delete.ts:8-12, 32, 36-48). That is the right behaviour for an agent that can delete things on its own initiative, but it means anything you would need gone this second should never have been written to a store in the first place. Secrets belong in neither layer.

FAQ

Should I delete my CLAUDE.md if I add a memory MCP server?

No. They hold different kinds of fact. CLAUDE.md holds the stable rules you would retype by hand — build command, package manager, directories that are off limits — and Claude Code loads it every session, so it is there whether or not anything asks for it. A memory store holds the by-products of doing the work, and nothing enters context until the agent runs a search. Deleting the file just moves guaranteed facts behind a retrieval step.

How is this different from Claude Code's built-in auto memory?

Auto memory is written by Claude rather than by you, lives in ~/.claude/projects/<project>/memory/, and Anthropic documents it as machine-local: all worktrees inside one git repository share a single auto memory directory, and files are not shared across machines or cloud environments (code.claude.com/docs/en/memory, verified 2026-08-03). A memory MCP server is written through a tool call from whichever MCP client you happen to be in, and is reachable from every machine you configure. If you work in Claude Code on one machine, auto memory may already be all you need.

Is Anthropic's memory tool the same thing as a memory MCP server?

No, and they are easy to confuse. The Anthropic API memory tool is an API-level tool definition ({"type": "memory_20250818", "name": "memory"}) that runs client-side: Claude issues view, create, str_replace, insert, delete and rename commands under a /memories prefix, and your own application executes them against storage you control (platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool, verified 2026-08-03). It is a building block for an application you are writing. A memory MCP server is a process your editor connects to over the Model Context Protocol, so it needs no application code from you.

Is "works with any MCP client" actually a product feature?

Not really, and we would rather say so. MCP is an open standard; its own specification says it takes inspiration from the Language Server Protocol, which standardised language support across a whole ecosystem of development tools (modelcontextprotocol.io/specification/latest, verified 2026-08-03). Any memory MCP server is reachable from any MCP client — that is the protocol working, not a vendor achievement. What actually differs between memory servers is governance: where the text is stored, and whether you can read, edit, export and delete all of it.

My team already shares an AGENTS.md. Do I still need a store?

If what you want to share is stable rules, no. AGENTS.md is an open format that the project reports is used by over 60k open-source projects across 24+ compatible platforms (agents.md, verified 2026-08-03), and Claude Code can pick it up through an @AGENTS.md import or a symlink. What a committed file cannot carry is the long tail — the dead ends, the constraint someone discovered on a Tuesday — because nobody hand-writes those into a file that goes through code review. That long tail is the only part a store adds.

The takeaway

Stable, human-curated facts go in a file the agent reads. Agent-accumulated, searchable facts go in a store the agent queries. If you only have the first kind of fact, you only need the first kind of tool — and stopping there is a completely legitimate place to land.

Set up the Kireo memory MCP What it stores

Last reviewed 2026-08-03.