Claude Code Long-Term Memory: Bigger Is Not the Same as Better

Ask about a decision from three weeks ago and a capture-only vault will hand you everything that was said near it. The profiler numbers. The rejected attempts. The message where the argument got settled. The answer is in there, spread across four sessions, and reassembling it takes ten minutes of skimming.

That is the moment the distrust starts. Capture worked, recall worked, and the vault still could not tell you what you had concluded. The pile just got taller.

Raw capture is the right foundation. It is also, on its own, a transcript archive with a search box. As it grows it gets harder to read, not easier. Near-duplicates multiply, stale wording crowds out settled conclusions, and the thing you actually want is a line that was never written down anywhere, because it was implied across a week of messages.

A transcript pile is not context

Two kinds of questions get asked of a memory vault, and they want different evidence.

Forensic questions want raw detail. What was the exact error string, what did the API return on Tuesday, what you said about the rollback path. The capture layer keeps all of it, verbatim.

Orientation questions want the distilled version. What do we know about this system, why is it built this way, what have we been prioritizing lately. A raw-only vault buries you in what was said instead of surfacing what it meant.

Consolidation is the layer that produces the distilled version, and it is the part of a memory system that decides whether the vault is still useful a year in.

Three tiers in one vault

Every MemoryRouter vault is organized into three tiers that stack on top of each other.

Tier 1 is raw. The captured turns, verbatim, with dates. Nothing is ever overwritten when higher tiers are written. The tiers layer.

Tier 2 is reflections: one clean line per thing that actually happened, written as standalone prose and rated 1 to 10 for importance. One example:

Thumbnail generation moved off the request path after profiling showed image decode dominating p99 latency.

Tier 3 is the distilled layer: what it all adds up to. Identity, principles, the pattern behind the decisions. The same thread, one level up:

This system trades feature immediacy for predictable latency.

Retrieval does not make you choose a tier. Searches blend all three and tag every result with the tier it came from, so an orientation question gets the distilled answer with the option to drop into the raw moment behind it.

Consolidation is a checkout and commit

The consolidation design is the part I would study before trusting any memory system, ours included. MemoryRouter never consolidates on its own, and it never calls a model. Your side drives the whole transaction:

1. Checkout takes the oldest unconsolidated memories, puts them under a fifteen minute lease, and returns their texts plus a versioned contract from the server: instructions for what the reflections should look like, and the entry schema (clean standalone prose, importance 1 to 10).
2. Your model writes the entries. Whatever model your app, agent, or CLI already runs is the one doing the writing.
3. Commit sends the entries back with the batch id. The server stores them at the tier above and builds lineage from its own records. The same loop runs one level up to turn reflections into the distilled tier.

A few properties that matter in production:

• The model never sees memory IDs. The batch id is a lease ticket, and all lineage is assembled server-side at commit time.
• A crashed run cannot wedge the vault. The lease expires and the material returns to the pool.
• Replays are safe. Committing the same batch twice returns the original reflection ids and writes nothing twice.
• Parallel loops cannot collide. Checked-out memories are excluded from new checkouts, so a backfill and a live session can run side by side.

The billing is deliberately boring: checkout meters as retrieval and commit meters as storage, both at the standard 1x raw rate. An empty checkout bills nothing, and a duplicate commit is not billed at all. The Reflections documentation has the full contract, including the lease and idempotency semantics.

One honest limit: reflections are written by a model, so a summary can be wrong. That is why the sources stay inspectable and every transaction is replayable. You are never asked to trust a summary blindly.

In Claude Code, it runs on your own machine

The Claude Code package wires this into the hook lifecycle, so you usually never think about it.

When a memory retrieval response reports reflection debt above the server's threshold, the hooks spawn the reflect loop as a detached background process. That process drives your local Claude Code with the server's instructions, commits what it writes, and repeats for up to three batches per trigger, re-checking debt between batches.

Four things keep it polite. A machine-wide lockfile stops multiple sessions from double-firing. A thirty minute cooldown follows each completed run. Failures never surface in your session and go to ~/.memoryrouter/consolidate.log instead. And the whole thing is opt-out with one config flag, autoConsolidate: false, while the manual commands keep working.

You can also run it by hand, which is the version I recommend the first time:

npx -y memoryrouter-claude reflect --dry-run

Drop --dry-run when the checkout looks right. --tier, --batches, and --max-tokens give you control over how much consolidates per run. The reflecting model is your own Claude Code, so you pay your own inference, same as any other claude -p run, and MemoryRouter bills the checkout and commit tokens at the normal rate. Your memory gets written by the model you already work with, on your machine, from a contract the server authored. The installation guide covers the commands and the health checks around them.

What a consolidated vault can answer

Once a vault has reflections, ordinary recall gets better, because a fresh session starts from the distilled version of a decision instead of the argument that produced it. Beyond that, the vault gains query power raw storage cannot offer.

The first is receipts. Every reflection can be inspected back to its sources: ask what a summary was built from and you get the memories one tier below it, with dates and content, chainable all the way down to the exact moment. The chain runs upward too, so a raw memory can show which reflections were built from it. Delete a source and nothing pretends otherwise; inspect reports the gap honestly.

The second is time-first search. The regular search endpoint is relevance-first; date search flips it and queries a window: what happened in February, in order, with an optional query to rank within the window. Reflections match on the period they cover, so February's reflections answer questions about February even though they were written in March.

There is also shaping: search and prepare accept tier and importance filters when you want a specific depth of context. Ask for tier 3 alone and you get the big picture with no raw noise. Set importance to 7 and you keep only what mattered, a filter that lands on reflections, since raw memories were never rated.

Watch the first batch

Setup lives on the Claude Code page: one install command, and the hooks handle capture and recall from there. Give the vault a week of real work, then run the dry run above and read what your own model wrote from your own sessions. The thing worth checking is whether it can still tell you what mattered three weeks in.

Create your MemoryRouter account, install the hooks, and watch the first reflection land.