How to make Claude Code remember project context across sessions

“How do I make Claude Code remember?” sounds like one question. It's five, and they have different answers. Getting a setup that actually holds means knowing which mechanism covers which gap, rather than piling everything into whichever one you found first.

Where the boundary actually is

Start with the thing being crossed. A session is the unit of memory: one conversation, one context. Anything not written outside it ends with it. Three events cross that boundary, and they're worth distinguishing because they fail differently.

1. You close the session. Clean break. Tomorrow's session is populated by files, instructions, and whatever you type.
2. The context compacts. A mid-session boundary you didn't ask for. Earlier turns are summarized, and specifics go first.
3. You switch tools. Claude Code to Codex, terminal to editor. A boundary in space rather than time, and nothing carries across it by default.

Any mechanism you pick has to be evaluated against all three, not just the first.

The five mechanisms

1. The context window

What it covers: the current task, completely and with no retrieval step. What it doesn't: any boundary at all. It's working memory, and it's volatile by design. Worth being clear that a larger window is a genuine improvement to mechanism 1 and changes nothing about mechanisms 2 through 5, because a window of any size starts empty.

2. Your repository

Re-read every session, so it always persists. It records the current state of the system perfectly. What it can't record is anything that isn't code: why a design was chosen over an equally reasonable alternative, what broke last time someone tried the obvious thing, which of two similar-looking functions is load-bearing.

People try to close this gap with comments, and comments are good, but they're limited to knowledge that has a natural home next to a specific line. “We evaluated three queueing approaches and here's why we picked this one” has no such line.

3. CLAUDE.md

Loaded in full, every session, every turn. That reliability is the point, and it's also the constraint: everything in it costs context on every message, so it has to stay short. Perfect for rules. Wrong for a growing pile of findings.

A good CLAUDE.md answers “how should you behave in this repo?” A bad one tries to answer “what do we know about this project?” and grows to two thousand lines nobody maintains. The trade in detail.

4. Built-in memory

Claude Code can record durable memories directly. This covers standing preferences and a handful of persistent facts well. It's deliberately bounded — it's designed for a short list, not for hundreds of project-specific findings, and it isn't project-scoped in the way a multi-repo workflow needs.

5. An external memory server

An MCP memory server gives the agent tools to write and search a store that lives outside every session. This is the only one of the five that crosses all three boundaries: it survives session end, it survives compaction (because the note was written before the compaction ran), and it survives a tool switch (because Codex can read the same store).

Its weakness is real and worth stating: it only contains what something wrote to it. A memory server nobody writes to is an empty database with good intentions.

How they combine

Nothing here replaces anything else. The working combination is: repository for code, short CLAUDE.md for rules, memory server for everything that accumulates.

The setup, concretely

Four steps, about five minutes.

Step 1: connect a memory server

claude mcp add --transport http knownbase https://knownbase.dev/mcp

Run /mcp to confirm. The first tool call opens a browser for sign-in. (Free workspace if you don't have one; full setup notes.)

Step 2: prune CLAUDE.md down to rules

Go through it and sort each section into rule or knowledge. “Run tests with npm test” is a rule; keep it. “The payments provider rate-limits per account, not per connection” is knowledge; it belongs in the memory store. Most bloated instruction files are 70% knowledge by volume.

Step 3: add the retrieval rule

## Project memory

This project has persistent memory via the `knownbase` MCP server,
under project "<your-project>".

Before starting work on an unfamiliar area, `search_notes` for prior
decisions, constraints and debugging findings about it.

When you finish something durable, `upsert_note` it: a decision and
its reasoning, a non-obvious root cause, an environment constraint,
an approach that was tried and rejected, or a handoff if you're
stopping mid-task.

Code lives in git. Store the reasoning here.

Step 4: seed it from what you already know

An empty store adds nothing, so prime it. Ask Claude Code to read your existing CLAUDE.md, your ADRs if you have them, and your last few weeks of commits, and to write the durable findings as notes. Ten minutes of seeding is the difference between a store that helps next week and one that helps in two months.

The habit that makes it work

Two moments, and they're both cheap.

At the start of a task: the agent searches for what's already known about the area it's touching. This costs one tool call and returns snippets, not full documents — usually less context than opening a single source file.

At the end of a task: the agent writes down anything durable it learned. The test for “durable” is simple: would a competent engineer looking only at the resulting code know this? If yes, don't store it — the code already says it. If no, store it.

If you're stopping mid-task rather than finishing, write a handoff instead: goal, state, decisions, dead ends, next step, pointers.

What good notes look like

Bad, because the code already says it:

Title: Auth uses JWT
Body: The auth middleware validates JWTs using the shared secret.

Good, because nothing else records it:

Title: Session tokens are opaque, not JWT — deliberate, don't "improve" it
Body: We evaluated JWTs for sessions in March and rejected them: we need
instant revocation on password change, and a stateless token can't do
that without a blocklist, which is a session store with extra steps.
Sessions are opaque ids hashed at rest in `sessions`.
API tokens are separate and are JWTs, which is why the codebase
appears to do both. src/auth/session.js:40.

The second one prevents a whole category of confident, wrong refactor. That's the shape you're aiming for.

Related reading

• Claude Code memory: the complete picture
• Claude Code keeps forgetting your project? How to add persistent memory
• What context compaction takes, and how to keep it
• Sharing the same memory with Codex

FAQ

How do I persist context between Claude Code sessions?

Layer three things: your repository for code, a short CLAUDE.md for standing rules, and an MCP memory server for accumulated knowledge. The first two persist automatically; the third needs connecting once and then a habit of searching at the start of a task and writing at the end.

Can I just paste a summary at the start of each session?

It works and it doesn't scale. You have to remember to do it, you have to know in advance what's relevant, and the summary has to be maintained by hand. A searchable store means the agent retrieves what's relevant to the actual task without you predicting it.

Should I keep using CLAUDE.md?

Yes. It's the right tool for standing instructions and nothing replaces it. Just keep it to rules and move accumulated knowledge somewhere searchable, so it can stay the short, always-loaded file it's good at being.

How do I stop the memory store filling with noise?

Give the agent an explicit test for what's worth storing: would a competent engineer looking only at the code know this? If yes, the code already says it and a note would just go stale. If no, store it. That one rule filters out most of what would otherwise become clutter.