MemoryRouterMemoryRouter
All posts

Persistent Memory for Claude Code: Lifecycle Hooks, Zero Dependencies, Compaction-Proof

John Rood··5 min read

Claude Code is the best coding agent on the market. It also forgets what you told it yesterday.

Not everything. Claude Code keeps machine-local auto memory notes, and CLAUDE.md holds whatever you write into it. But the conversation itself, the actual context you build up across a session (the bug you traced together, the architecture call you made at 11pm, the reason you rejected the obvious approach), lives in the context window. And the context window has two exits: the session ends, or compaction eats it.

[email protected] is the current npm release and gives Claude Code persistent memory in one command:

npx -y [email protected] init

That is the whole install. Two minutes, including signup. Here is what it actually does and why we built it this way.

The three ways Claude Code loses context

Cold sessions. Every new session starts from whatever is in CLAUDE.md plus auto memory notes. The detailed conversational context from yesterday (what you tried, what failed, what you decided) is not there. You re-explain, or the agent rediscovers things it already learned.

CLAUDE.md bloat. The standard workaround is stuffing everything into CLAUDE.md. It works until it doesn't. The file grows, every session pays the token cost of the whole file, and most of it is irrelevant to the task at hand. Static context does not scale; you need retrieval.

Compaction. This is the silent one. Long sessions hit the context limit, Claude Code compacts the conversation into a summary, and the details are gone. The summary keeps the shape of the conversation but loses the specifics: exact error messages, the precise reasoning behind a decision, the thing you said once and assumed the agent would keep. After compaction, your agent is working from a paraphrase of its own past.

MemoryRouter addresses all three with the same primitive: a memory vault outside the context window. Published v2.1.0 hooks retrieve before prompts and durably capture one typed user prompt plus one final user-visible assistant response for each completed turn. Tool payloads and intermediate transcript data are excluded.

How the lifecycle hooks work

memoryrouter-claude wires Claude Code's supported lifecycle events. No daemon, no wrapper binary, no patched install. Just hooks.

  • SessionStart warms the project vault, retries pending typed events, and re-injects memory after startup, resume, fork, or compaction.
  • UserPromptSubmit creates one typed user-prompt event while retrieving relevant project memory in parallel.
  • Stop durably accepts one typed final user-visible assistant response.
  • StopFailure retries the pending prompt but never invents a final response.
  • PreCompact and PostCompact retry events that were already created. They do not sweep the transcript or store a compaction summary.
  • SubagentStop is excluded from automatic capture.
  • SessionEnd retries pending typed events without scanning the transcript.

Capture advances its local checkpoint only after the API returns a durable accepted or duplicate receipt for the same idempotency key.

The flow on any given prompt looks like this:

you type a prompt
  -> UserPromptSubmit hook fires
  -> POST /v1/memory/prepare with the prompt
  -> relevant memories come back in ~100ms
  -> injected into context before the model sees your prompt
  -> Claude answers with yesterday's context in hand

The hero feature: compaction-proof memory

PreCompact is the hook we are proudest of. Everyone who runs long Claude Code sessions knows the feeling: the agent compacts, and afterward it is subtly dumber about everything that happened before. It remembers that you debugged something, not what the fix was.

Before compaction runs, the PreCompact hook retries any typed prompt/final events that were already created but not yet acknowledged. It does not dump the transcript or compaction summary. The context window can shrink without silently abandoning a pending durable capture. Three hours later (or three weeks later, on a different machine), the accepted user request and final response remain retrievable.

This is the difference between memory that lives inside the context window and memory that lives outside it. Inside, everything is temporary. Outside, it compounds.

Built to be trusted

We assumed you would be skeptical of anything that hooks into your coding agent. Fair. So:

  • Fails open. If the MemoryRouter API is down, slow, or unreachable, every hook exits cleanly and Claude Code proceeds as if nothing happened. Memory is an enhancement, never a gate. Your agent is never blocked by our uptime.
  • Zero dependencies. The package has no npm dependencies. What you install is what runs.
  • Your key stays local. Stored at ~/.memoryrouter/config.json with 0600 permissions. It is never written into your Claude Code settings or your repo.
  • Non-destructive merge. init merges hooks into your existing Claude Code settings without touching anything else you have configured.
  • Clean uninstall. npx -y [email protected] off removes the hooks and restores your settings. npx memoryrouter-claude status shows your vault stats any time.

Cross-surface, not just cross-session

The same selected vault can power our Claude Cowork connector. Decide something in Claude Code on your laptop, and Claude on claude.ai already knows about it. Discuss a project in Cowork, and your next Claude Code session starts with that context. Memory that follows you across surfaces, machines, and sessions is the actual product. The hooks are just the plumbing.

Setup

npx -y [email protected] init

It asks for your Memory Key (grab one at app.memoryrouter.ai/signup), lets you choose project/local/user settings scope, and wires the hooks without replacing unrelated settings. Then run npx -y [email protected] doctor and complete the two-session verification in the full installation guide.

Every plan starts with a 14-day free trial, no charge today. Starter is $20/mo with 200M memory tokens included (then $0.50/1M). Growth is $100/mo with 1B tokens (then $0.20/1M). Scale is $200/mo with 2B tokens (then $0.10/1M). BYOK, no inference markup.

If it is not obviously better within the trial, npx -y [email protected] off and you are back to stock in one command.

Start free | npm package | /claude-code

All posts