CLAUDE.md vs persistent project memory: when you need both

CLAUDE.md is good. So is AGENTS.md, and so are Cursor rules — this argument applies identically to all three. None of them is the problem. The problem is that they're the only durable place most projects have, so everything durable ends up in them, including things they were never shaped to hold.

The one difference that decides everything

An instruction file is loaded in full, on every turn. A memory store is searched on demand. Every other difference follows from that.

Read the last row again, because it's the whole heuristic. Always-relevant goes in the file. Sometimes-relevant goes in the store.

Why files grow

Every line in a bloated CLAUDE.md got there for a good reason. An agent made a mistake; you wrote a line to stop it happening again. Repeat for eight months.

The failure isn't the individual decisions, it's that they compound in the wrong container. By line 1,500 the file has three problems at once:

• Cost. Every message pays for the whole file, including the 95% irrelevant to the current task.
• Dilution. The three lines that matter today are surrounded by 1,497 that don't, and attention is finite.
• Rot. Nobody re-reads 1,500 lines to check what's still true, so stale entries accumulate and quietly contradict newer ones.

None of these is solved by trying harder. They're solved by moving the growing part somewhere designed to grow.

Sorting the file

Go through it line by line with two questions.

“Does this apply to every task in this repo?” If yes, it's a rule. Keep it.

“Is this something we learned?” If yes, it's knowledge. Move it.

Stays in CLAUDE.md

- Run tests with `npm test`. There is no linter and no build step.
- This project has exactly two npm dependencies. Don't add more
  without asking.
- Match the surrounding code's comment density and naming.
- Never commit unless asked. Branch first if on main.
- Node >= 22.5.0.

Short, universal, cheap. This is the file doing what it's for.

Moves to project memory

- The settlement provider rate-limits per account, not per connection,
  so the export job can't be parallelised. Tried worker pools and
  connection-per-shard; both trip 429.
- We evaluated JWTs for sessions in March and rejected them because
  instant revocation matters more than statelessness.
- The staging database is restored from a nightly snapshot, so any
  fixture written after 02:00 UTC is gone by morning.
- The retry wrapper must not regenerate the idempotency key.
  That caused a double-charge incident in June.

Each of these is valuable, specific, and relevant to maybe one task in fifty. Paying for all of them on every message to have them available for 2% of tasks is the wrong trade — and it's exactly the trade an instruction file forces.

What replaces them in the file

One short section. It's a rule, so it belongs in the rules file, and it stays this size forever:

## Project memory

This project has persistent memory via the `knownbase` MCP server,
under project "<your-project>".

Before starting work on an unfamiliar area, `search_notes` for prior
decisions, constraints and debugging findings about it.

When you learn something durable, `upsert_note` it: a decision and
its reasoning, a non-obvious root cause, an environment constraint,
an approach that was tried and rejected.

Code lives in git. Store the reasoning here.

Ten lines that make an unbounded amount of knowledge reachable. That's the trade the split buys you.

Where the instruction file still wins

It would be dishonest to present this as one-directional. Instruction files have a real advantage that memory stores can't match: they can't be missed. There's no retrieval step, so there's no chance the agent fails to find them.

That matters for anything where a miss is expensive. “Never run migrations against production” belongs in the file, even though it's arguably knowledge, because a search that doesn't happen to surface it is a genuine hazard. The rule of thumb: if forgetting it once is unacceptable, pay the always-loaded cost.

Likewise, a memory store has a failure mode the file doesn't: it depends on the habit. Nobody has to remember to load CLAUDE.md. Somebody has to remember to write notes.

Doing the migration

1. Create a workspace and connect it: claude mcp add --transport http knownbase https://knownbase.dev/mcp
2. Ask the agent to read your current CLAUDE.md and sort every section into rules vs knowledge. It's good at this, and reviewing its split is faster than doing it yourself.
3. Have it write each knowledge item as a note, tagged by kind (decision, constraint, debugging, rejected-approach).
4. Trim the file to the rules plus the memory section above.
5. Keep the trimmed file in git as usual. You've lost nothing — it's all still in version control, and now also in something searchable.

A typical 1,500-line file comes out somewhere around 120 lines, with the rest as sixty or so notes. Every future finding goes to the store instead of the file, so the file stays that size.

Related reading

• Claude Code memory: what persists today
• Making context survive across sessions
• The same split for Codex and AGENTS.md
• MCP memory servers explained

FAQ

Is CLAUDE.md still worth using?

Yes, absolutely. It's the right tool for standing rules and nothing replaces it. The argument here isn't against instruction files, it's against using one as a knowledge base, which is a job it was never shaped for.

How large is too large for CLAUDE.md?

There's no hard number, but the symptoms are clear: you stop re-reading it, entries start contradicting each other, and most of it is irrelevant to any given task. In practice people start feeling this somewhere past a few hundred lines.

Does the same apply to AGENTS.md and Cursor rules?

Identically. All three are always-loaded instruction files with the same size ceiling and the same reason for it. The split between rules and accumulated knowledge is the same wherever you're working.

What if the agent doesn't search memory when it should?

That's the real failure mode of a memory store, and it's addressed by the instruction file — a short rule saying when to search. Which is a nice illustration of the point: the two mechanisms are complements, and the file is what makes the store reliable.

Can I keep some knowledge in both places?

Yes, and for a few high-stakes items you should. Anything where forgetting once is unacceptable — destructive commands, production safety rules — is worth the always-loaded cost even though it's technically knowledge.