Beyond CLAUDE.md: What Claude Code Loses at Compaction

CLAUDE.md is a good place for the rules you want followed every session: conventions, commands, architecture facts, "never touch this file." Teams treat it as the project's memory, and for a while it feels like one.

Then you watch a session go wrong. Claude proposes the approach you rejected on Tuesday, with the same confidence as the first time. Compaction fired an hour ago, and the reasoning that killed that approach lived in the conversation, not in any file. CLAUDE.md survived. It just never contained the part that mattered.

MemoryRouter exists for that layer: a vault outside the context window that stores what happened, so the next session can retrieve it. Before adding anything, it helps to see exactly where the file-based approach ends.

What CLAUDE.md is genuinely good at

• Standing instructions: style, tool choices, review expectations.
• Facts that are always true: "the API lives in workers/", "we use pnpm."
• Guardrails: "never edit generated migrations by hand."

All of that is static, stable, and small. A healthy CLAUDE.md is boring. If yours grows every week, that is a symptom, not progress.

What a file cannot hold

A file holds what you write into it. The value of a session is mostly in what nobody writes down:

Decisions with reasoning. "We went with the queue because the upstream service bursts and retries are not safe." The decision might get one line somewhere. The reasoning almost never does, and the reasoning is what stops the next session from reversing it.

Dead ends. The two approaches that failed, and the exact failure. Rejected work is the most expensive context to lose, because an agent without it will happily repeat the journey.

Constraints discovered mid-task. "The staging key cannot write to that bucket." Learned at 2pm, buried by 3.

Task state. What is done, what is in review, what is waiting on a person. The next session reconstructs this from scratch, or asks you.

Corrections. The things you said once and expected to stick.

The compaction problem specifically

Long Claude Code sessions compact: the conversation is summarized to stay inside the window. Summaries keep the shape of the work and lose the specifics. The exact error string, the reason behind the design call, the constraint you mentioned once, all compress into a sentence that is technically true and practically useless.

Two things are true at once here. Compaction is necessary, and most of what it trims was worth keeping. The layer that resolves the contradiction is storage outside the window, written as the work happens.

Why writing more into CLAUDE.md is not the fix

Every team tries the same escalation: a session forgot something, so the file gets longer. But the file is read in full, every session, mostly for nothing. You end up paying tokens for stale history so that the occasional line is present. Worse, the file cannot update itself. It captures only what someone remembered to write down after the fact, which is a different list from what the agent actually needed.

The right split is not "more file." It is a second layer with different physics: written by the system as work happens, retrieved by relevance instead of by position in a document, and scoped to the project rather than the person.

The layer to add

npx -y memoryrouter-claude init

That installs hooks into Claude Code's lifecycle. What they do, in the order you will notice:

• Recall before prompts. Relevant project memories are retrieved and injected alongside your prompt, every turn, without the model needing to call a tool.
• Capture after turns. One user prompt and one final, user-visible assistant response per completed turn. Tool calls, patches, thinking, intermediate text, and subagent chatter are excluded.
• Recovery at the edges. Session start re-injects memory after startup, resume, and fork. Compaction events retry pending writes, so a compaction cannot eat a turn that was mid-flight.
• Failure, handled. Hook failures fail open, so a network problem never blocks your session.

Project identity is derived from the repository (git remote or project folder), not the absolute path, so worktrees of the same repo share memory and clones on other machines line up too. The key stays in your home directory, never in .claude/settings.json or the repository.

Verify with npx -y memoryrouter-claude doctor, then run the code-phrase test from the installation documentation: teach a phrase in one session, ask for it in a new one.

What goes where

| CLAUDE.md | Memory vault | | --- | --- | | Rules that must be followed literally | Decisions and the reasoning behind them | | Stable facts about the codebase | Dead ends and failure details | | Commands and conventions | Constraints discovered during work | | Always-on guardrails | Task state and corrections |

The sorting rule is simple: instructions belong in the file, history belongs in the vault. When you catch yourself pasting history into CLAUDE.md to "make it stick," that is a sign the file is being asked to do a job it cannot do for long.

The vault is the same cross-AI memory layer that connects to every other tool you use, so a decision captured here is also available in Cursor, ChatGPT, or wherever the next task starts. Boundaries worth knowing: the hooks capture your typed prompt and the final response, not a full transcript archive. The optional MCP tools are additive, for explicit search and store, and the automatic behavior comes from the hooks. The Claude Code page has the short path, and this earlier write-up covers how the pieces fit together.

Start with the rules file you already have

Open CLAUDE.md, and move anything that reads like a story rather than a rule into one install session. Ten minutes later it has a different home.

Create your MemoryRouter account and install the hooks in the project where you feel the losses most.