How to give Claude Code persistent memory

Why does Claude Code forget everything?

Claude Code is brilliant inside a session and amnesiac across them. The reason is simple: a context window is working memory, not storage. It is bounded, it is expensive to refill, and it is wiped when the session closes. The model's own working memory effectively expires within minutes of inactivity, so nothing survives a lunch break — let alone a new project, a different machine, or a teammate.

The practical cost shows up every time you start over. Re-orienting a fresh agent — re-explaining the architecture, the constraints, the bug you already fixed — commonly burns 30,000 to 150,000 tokens before it does anything useful. Multiply that by every session, every developer, every day.

Isn't a bigger context window the same as memory?

No — a bigger context window is more RAM, not a hard drive.

A context window holds what the agent is thinking about right now. It is bounded, you pay to refill it on every session, and it resets to empty when the session ends. Memory is the opposite: it is the part that survives the boundary — across sessions, tools, models, and machines. Stretching the window makes a single session see more at once; it does nothing to carry knowledge into the next one. The fix for forgetting is not a larger window. It is durable storage the agent can write to and read from.

What is MCP, and how does it add memory?

The Model Context Protocol is the open standard Claude Code uses to connect to external tools and servers. A memory server is one such server: it exposes save and search tools that the agent calls as it works. The decisions and fixes are written to a store that lives outside the model, and a later session retrieves them with a short semantic or keyword query.

Because the store sits outside the model, your memory is portable across any model — switching from one model to another costs you nothing — and it can be shared across tools and teammates, not locked inside one vendor's per-app memory.

How do you give Claude Code persistent memory with Supabrain?

Supabrain is a local-first memory that connects to Claude Code as an MCP server. Setup is one connection, then it works on its own:

1. Connect once over MCP. Add Supabrain to your MCP client's configuration as a single memory server. Claude Code launches it and gains save and search tools.
2. Capture as it works. The agent records the decisions, fixes, and dead ends it produces. A validator checks each entry on the way in, so the store stays signal — not a junk drawer.
3. Recall next session. On any machine, in any MCP client, the agent pulls the right memory in one short query. No cold start, no re-explaining.
4. Compound across tools and team. The same store is shared with Cursor, any other MCP client, and your teammates, so one person's solved problem becomes everyone's.

Everything is local-first: embeddings and search run on your machine, and nothing leaves it unless you turn on sync.

What should Claude Code actually remember?

Not transcripts — durable knowledge. The highest-value memories are the ones most expensive to rediscover:

• Decisions and their rationale — why the code looks the way it does, so a future session doesn't quietly undo it.
• Fixes and their root cause — so the same bug is never solved twice.
• Ruled-out hypotheses (negative knowledge) — the dead ends you already explored. The most expensive thing to rediscover, and the first thing an agent forgets.
• Project conventions — the naming, structure, and invariants that keep edits consistent.

Frequently asked questions