Claude Code memory: CLAUDE.md vs MinniMemoryMCP

How Claude Code loads memory#

• CLAUDE.md files in your project folder and the folders above it load when a session starts. One in a subfolder loads once Claude works in that subfolder.
• Imports: a line like @docs/testing.md in a CLAUDE.md pulls that file in at the start too, and imported files can import more.
• Your user file, ~/.claude/CLAUDE.md, loads in every project.
• Auto memory: Claude keeps its own notes in a memory folder for each project, with MEMORY.md as the index. The start of MEMORY.md loads in every session. The topic files it lists are read only when a task needs them.

Source: Anthropic’s memory docs. The point to take away: a file that a CLAUDE.md imports is not loaded on demand. It loads every time.

How memory gets expensive#

Memory files only grow. Every correction, project and decision becomes a line, and every import adds a whole file. After a few months, the part that loads on every turn carries project histories, runbooks and old decisions that matter to a handful of tasks, and every turn pays for them.

Good candidates to move out of the part that always loads:

• Project histories and change logs.
• Runbooks and command references.
• Past decisions and the reasons behind them.
• Anything dated that changes often.

What should stay: the rules the agent must follow on every turn, who you are and how you like to work, and one line per moved file that says when to open it.

Making the split by hand#

1. Read your CLAUDE.md and every file it imports. Mark each section “every turn” or “sometimes”.
2. Move each “sometimes” section into its own file, and remove its @ import.
3. In the file that always loads, add one line per moved file that says when to open it, not what it says. For example: “Before a database migration, read docs/migrations.md.”
4. Check that nothing was lost. Redo it whenever the memory grows.

This works. The cost is the time it takes, and the habit of doing it again.

Making the split with MinniMemoryMCP#

MinniMemoryMCP is an MCP server for Claude Code that makes the same split. It reads the same files you would, and it never deletes a line.

• init reads your memory and shows the plan: what stays, what moves, and the tokens loaded on every turn before and after.
• apply gives Claude the command and the list of changes. Claude runs it with your approval, after every original is backed up.
• doctor checks later whether the memory has drifted and needs another pass.
• undo restores the originals byte for byte.

$ npx -y minnimemory install

On our full-size test memory, the part loaded on every turn went from 12,511 to 6,699 tokens, and every line was kept.

We ran the same 27 coding tasks in Claude Code 2.1.292 on Claude Sonnet 5.5, three full sessions a side: once with a full-size test memory as it was, and once after MinniMemoryMCP sorted it. The three sessions cost $2.31 before and $1.68 after, 27.4% less. A blind grader marked 74 of 81 answers correct before and 72 of 81 after.

By hand or with the tool#

Why memory size matters for the bill is in Why Claude Code sessions get expensive. The other ways to cut tokens are in How to reduce Claude Code token usage.