How to Give Claude Code Long Term Memory (2026)

Originally published on contextforge.dev.

How to give Claude Code long term memory is a question I get in some form every week, and the honest answer is that there is no single switch. There are four layers, each one remembers a different kind of thing, and most people stop after the first.

I build ContextForge, a memory layer for Claude Code, Cursor and Copilot, so I have an obvious interest here. I'll be clear about where my own tool fits and where it doesn't.

TL;DR: put stable rules in CLAUDE.md, leave a handoff note at the end of each session, add a memory server over MCP for decisions and facts that change, and make sure that memory gets re-injected after Claude Code compacts. Each layer covers what the one before it loses.

Why Claude Code forgets in the first place

Claude Code has a context window, not a memory. A session can hold a lot (200k tokens on the standard tier, and 1M on the larger one), but when it ends, everything in it is gone. When it gets long, Claude Code compacts it: the conversation is replaced with a summary, and the summary drops details. The decision you made two hours ago about the retry policy is exactly the kind of detail that goes.

So "long term memory" really means two different problems: surviving the end of a session, and surviving compaction inside one. The layers below handle both.

Layer 1: CLAUDE.md for the things that don't change

Claude Code reads CLAUDE.md from the repo root at the start of every session. That makes it the right place for stable facts: how to run the tests, which package manager you use, naming conventions, the rule that nobody touches the migrations folder without asking.

It is the wrong place for anything that changes often. People try to turn it into a diary, and the file goes stale within a couple of weeks. A stale rule is worse than no rule, because Claude follows it with confidence. Keep it under a page, and treat every line as something you'd be fine with being enforced for the next six months. Anthropic's own guidance on memory in Claude Code covers the file locations.

Layer 2: a handoff note at the end of each session

Before you close a session, ask Claude Code to write down where things stand: what's done, what's half done, what it decided and why, what it would do next. A few lines in a NOTES.md or the task tracker are enough. The next session starts by reading it.

This is cheap and it works, which is why I wrote a whole post on it: Claude Code session handoff: how to resume work without re-explaining everything. Its weakness is that it's manual. The day you forget to write the note is the day you needed it.

Layer 3: a memory server over MCP for decisions and facts

This is the layer that makes the memory searchable instead of a pile of notes. The Model Context Protocol lets Claude Code call tools from an external server, and a memory server gives it two that matter: one to save a memory, one to search them by meaning.

With ContextForge, the setup in a repo is one command:

npx contextforge-mcp init

That links the folder to a project, so every agent working in that repo (Claude Code today, Cursor tomorrow) searches the same memories. From then on, when something worth keeping happens, you say it: "Save to ContextForge: we dropped automatic retries on the payment webhook because they double-charged a customer." Weeks later, in a new session, "why don't we retry the payment webhook?" finds it, because the search is semantic, not keyword matching.

Two honest notes. First, it saves what the agent is told to save, either by you in the moment or by rules in CLAUDE.md that tell it what counts as worth keeping. It does not read your mind, and a memory nobody writes to is empty. Second, this is hosted: the MCP server is open source, the storage behind it is not something you run yourself. If your constraints say the data cannot leave your machine, I wrote up what self-hosted memory for AI agents actually takes, including the options that aren't mine.

Layer 4: get the memory back after compaction

This is the step almost everyone misses. Even with a memory server, compaction inside a long session leaves Claude Code with a summary and no idea that the memories exist until it thinks to search. So after a compaction it quietly goes on with less context than it had a minute earlier.

ContextForge handles this with a Claude Code hook that init installs: right after every compaction, it re-injects your most recent memories for that project and your pending tasks. You don't have to notice the compaction happened. If you don't use ContextForge, you can get a weaker version of the same thing with a hook that re-reads your handoff note after compaction. The post on how to stop Claude Code from losing context walks through the hook mechanics.

The four layers side by side

Layer	Remembers	Survives	Cost
CLAUDE.md	Stable rules and project facts	New sessions, compaction	Goes stale if you put changing things in it
Handoff note	Where you left off	New sessions	Manual, easy to skip
MCP memory server	Decisions, facts, why things are the way they are	New sessions, other tools, other machines	You have to tell it what to save
Post-compaction recall	Everything above, mid-session	Compaction	Needs a hook; only ContextForge installs it for you today

Keeping the memory honest

A long term memory accumulates mistakes. The database moved, the API got renamed, and the memory still says the old thing. ContextForge has tools for this: Claude Code can check a memory's freshness against recent commits, confirm it, correct it, or forget it, and the git integration keeps commits and pull requests in the same store so the memory can tell when the code moved on. The knowledge graph links related memories, so correcting one shows you what else depended on it. None of that is magic. It's the difference between a memory you trust and one you learn to ignore.

FAQ

Does Claude Code have built-in long term memory?
It has CLAUDE.md files, which it reads at the start of every session, and that's it. Nothing is saved from a session unless you or a tool writes it somewhere.

Is CLAUDE.md enough on its own?
For a small project with stable conventions, often yes. It stops being enough when the things you need remembered change weekly, because the file goes stale and Claude Code follows stale rules confidently.

Does memory survive compaction?
Not by itself. Compaction replaces the conversation with a summary. You need something that re-injects context afterwards: ContextForge's post-compaction recall does it automatically, or a hook that re-reads your notes.

Can Cursor and Claude Code share the same memory?
Over MCP, yes. ContextForge links a repo to one project, and every MCP client working in that repo reads and writes the same memories.

Where to start

If you have nothing today, write the CLAUDE.md and the handoff note this week; that alone fixes most of the pain. When you catch yourself re-explaining a decision for the third time, add the memory server:

npx contextforge-mcp init

Then save one real decision, close the session, open a new one, and ask about it. That first answer from a fresh session is when it clicks.