MEMORY.md vs CLAUDE.md — what goes where? (settling the most common setup question)

[manja316]

This trips up almost everyone setting up persistent memory in Claude Code, so let's settle it in one thread.

Both files get loaded into context, but they do different jobs:

CLAUDE.md — instructions / standing rules

• Who the agent should be and how it should behave: tone, coding conventions, "always run tests before claiming done," project constraints, do/don't lists.
• It's prescriptive. It's read every session as law.
• Stays fairly stable. You edit it when your preferences or the project's rules change.

MEMORY.md — an index of facts, not the facts themselves

• A one-line-per-memory table of contents that points to individual fact files (- [Title](file.md) — hook).
• Each real memory lives in its own small file with frontmatter (type: user | feedback | project | reference) so recall can pull only what's relevant instead of dumping everything into context.
• It grows over time as the agent learns things that aren't derivable from the code or git history.

Rule of thumb I use:

• If it's "this is how you should work" → CLAUDE.md.
• If it's "this is something true that you learned and shouldn't have to be told again" → a memory file, indexed in MEMORY.md.
• If the repo/git history already records it (code structure, past fixes) → neither. Don't duplicate what the codebase already says.

The failure mode to avoid: stuffing facts into CLAUDE.md. It bloats every session's context with stuff that's only relevant 5% of the time, and CLAUDE.md becomes unmaintainable. The index-plus-files pattern exists precisely so recall stays cheap.

How are you splitting yours? Curious where people draw the line — especially anyone putting project state (current goals, blockers) into CLAUDE.md vs a project-type memory. There's a real trade-off and I don't think there's one right answer.