Claude Code Memory Between Sessions: What Actually Works

Direct answer: Claude Code has two native memory mechanisms — CLAUDE.md files (instructions you write) and auto memory (notes Claude writes itself from corrections) — and both are loaded at the start of every session. The catch: they're file-based and local to your machine or repo. Unless you commit CLAUDE.md to git, it doesn't sync to teammates, and neither mechanism gives you searchable retrieval, semantic recall of prior decisions, or a way to bring that context into Cursor, Windsurf, or another agent. If you want memory that's actually shared and searchable across sessions and tools, you need a layer on top — that's what an MCP server like ContextStream is for.

If you've used Claude Code for more than a few sessions, you already know the feeling: you fix a bug, explain why you fixed it that way, move on — and three days later Claude tries the same broken approach again. The context didn't disappear because Claude is bad at its job. It disappeared because nothing built a durable record of it.

How Claude Code memory actually works today

Per Anthropic's own documentation, Claude Code has two mechanisms, both loaded at the start of every session:

1. CLAUDE.md files — persistent instructions you write yourself. These can live at managed policy, user, or project scope.
2. Auto memory — notes Claude writes on its own, generated from corrections you give it mid-session.

Both are real and both work as advertised for what they are: text files that get read back into context at session start (Claude Code memory docs). Anthropic also ships a separate mechanism called Skills, for packaging reusable procedures Claude can invoke — a different problem (capability packaging) from memory (fact persistence).

The limitation isn't that these mechanisms are broken. It's that they're file-based and local to the machine or repo. A CLAUDE.md file only travels as far as your .git history takes it. If you don't commit it, your teammate's Claude Code session never sees it. If two people edit CLAUDE.md differently in different branches, you get silent drift, not a merge conflict warning. And nothing about the mechanism gives you semantic search over months of accumulated decisions — you're limited to whatever fits in a markdown file that gets fully re-read every session.

This is why CLAUDE.md is what most teams reach for first, and also why it stops being enough the moment more than one person or more than one repo is involved.

Why "context between sessions" actually breaks down

There are four separate failure modes hiding inside the general complaint of "Claude Code forgets things":

1. Decisions don't persist past the conversation. You explain why the team chose Postgres over DynamoDB for a specific reason six weeks ago. That reasoning lived in a chat transcript, not a durable record. New sessions start from zero.

2. Corrections get relearned, not remembered. You tell Claude "don't use that deprecated auth pattern" in one session. Auto memory captures it as a note — but if it's not indexed and retrievable across every future session and repo, the same mistake resurfaces in a different context window.

3. CLAUDE.md doesn't sync across teammates. If it's not in git, it's local. If it is in git, it's static text — no per-teammate scoping, no retrieval logic, no way to know which of the 40 accumulated rules are actually relevant to the file you're editing right now.

4. Nothing crosses the tool boundary. CLAUDE.md is a Claude Code-specific convention. It does not travel to Cursor, Codex, or Cline. If your team uses more than one AI coding tool — and most do — the context you built in Claude Code is invisible everywhere else.

The workflow: adding a persistent, shared memory layer

The fix isn't to abandon CLAUDE.md — it's to add a layer that does what file-based memory structurally can't: cross-session, cross-teammate, cross-tool retrieval. Here's the practical setup using ContextStream, written in Rust and ships as a compiled binary (not an npm package):

Step 1 — Install the MCP server.

macOS/Linux:

Windows:

Step 2 — Run setup, which connects to Claude Code (and Cursor, Windsurf, Cline, and other MCP-compatible tools) via contextstream-mcp setup. Claude Code is one of the editors ContextStream's setup wizard configures automatically, alongside managed rules and lifecycle hooks.

Step 3 — Let the memory system do the capturing. Once connected, decisions, lessons, preferences, plans, tasks, docs, and runbooks get captured and indexed rather than living only in a markdown file or a chat transcript. The mechanism is explicitly designed for the same problem CLAUDE.md addresses — "why did we choose X, nobody remembers" — except retrieval is semantic and it isn't capped by what fits in a file that gets fully reloaded every session.

Step 4 — Use pre-compaction capture. One specific, verifiable failure mode CLAUDE.md doesn't touch at all: context loss when a conversation gets long enough to trigger compaction. ContextStream's design captures critical state before compaction happens and restores it after, rather than relying on auto memory to have already written down whatever mattered.

Step 5 — Bring the same memory into other tools. Because the retrieval layer isn't file-based, the same project memory that Claude Code built is available the next time someone opens the same project in Cursor — closing the tool-boundary gap CLAUDE.md can't close by design.

Comparison: CLAUDE.md/auto memory vs. an MCP memory layer

This isn't a case for ripping out CLAUDE.md — keep using it for static conventions. It's a case for not expecting a static file to do a database's job.

What this looks like in a real multi-repo team

Here's a scenario that shows why file-based memory breaks down specifically at team scale, not just individual use. Say your team maintains four repos: an API, a web frontend, a mobile client, and a shared internal library. A backend engineer working in Claude Code discovers that a particular caching pattern causes a race condition under load, and fixes it. With CLAUDE.md alone, that lesson lives in one repo's file, written by one person, in one session. It does not automatically appear when:

• A different engineer touches the same caching logic in the shared library repo three weeks later.
• The same engineer opens a different repo that has a structurally similar pattern.
• Anyone uses Cursor instead of Claude Code for the follow-up work.

A searchable memory layer changes this by treating the lesson as a retrievable fact scoped to the workspace or project, not to a single file that has to be manually duplicated into every repo where it might matter. That's the practical difference between "I wrote it down somewhere" and "the next session already knows."

What to capture first if you're starting from zero

If you're introducing a memory layer into an existing Claude Code workflow, don't try to backfill everything at once. Start with three categories that give the fastest payoff:

1. Standing architecture decisions — the ones you'd otherwise have to re-explain to a new hire or a new AI session. Why this ORM, why this deployment model, why this repo is structured the way it is.
2. Corrections you've had to repeat. If you've told an AI coding assistant "don't do that" more than once for the same pattern, that's a signal the lesson isn't sticking anywhere durable.
3. Runbooks for anything you'd otherwise Slack a teammate about. Deploy steps, rollback procedures, environment quirks — anything currently living in someone's head or a stale wiki page.

That's a smaller, more honest starting point than trying to migrate an entire team's tribal knowledge on day one, and it's enough to prove whether the workflow actually changes session-to-session behavior before expanding further.

Where the evidence gets honest about limits: ContextStream's own memory and code-search benchmarks show this isn't magic. On the 500-instance LongMemEval-S memory benchmark, ContextStream scores 90.0% overall using a self-consistency reader — but the multi-session-recall category specifically caps at 81.2%, and a documented follow-up test tried three different reader strategies to push that number higher and none of them worked. The team's own conclusion, published alongside the result: "retrieval is not the limiter" — the ceiling is in how well the reasoning model counts across multiple sessions, not in whether the right memory got retrieved (evidence-session recall is 98.4%). That's a real, disclosed limitation, not a marketing number — and it's a more honest data point than most vendors publish.

FAQ

Does Claude Code have memory built in?
Yes — two mechanisms: CLAUDE.md files you write, and auto memory that Claude generates from corrections. Both load at the start of every session, but both are file-based and local unless you commit CLAUDE.md to git (Claude Code memory docs).

Why does Claude Code forget things between sessions?
Because neither CLAUDE.md nor auto memory gives you semantic, searchable retrieval — they're re-read as flat files. If the relevant fact isn't in that file, or the file has grown too large and unfocused, it doesn't surface. There's also no built-in mechanism to sync memory across teammates unless the file is committed to version control.

Does adding a memory layer replace CLAUDE.md?
No. CLAUDE.md remains useful for static, explicit project conventions. A memory layer like ContextStream adds what CLAUDE.md structurally can't do: searchable retrieval of decisions and lessons, cross-teammate sync, pre-compaction state capture, and portability to other MCP-compatible tools.

Is ContextStream free to try with Claude Code?
Yes — the Starter tier is free forever, no credit card required, with 3,000 monthly credits, core memory and search, and 5-day memory retention.

Does this work if my team also uses Cursor or Windsurf?
Yes — ContextStream's MCP server supports Claude Code, Cursor, Windsurf, Cline, Roo Code, Kilo Code, VS Code with GitHub Copilot, Codex CLI, OpenCode, Aider, Antigravity, and Claude Desktop, so memory captured in one tool is retrievable in another.

Try it on one repo

Point ContextStream at a single repo before rolling it out anywhere else. Install with curl -fsSL https://contextstream.io/scripts/mcp.sh | bash (or the Windows PowerShell command above), run contextstream-mcp setup, and start capturing decisions on your next Claude Code session. Free forever, no credit card required.