Giving Claude Code a Memory That Survives the Session

Claude Code starts every session with an empty context window. Three things carry knowledge from one session to the next: the CLAUDE.md files you write, the auto memory Claude writes for itself, and the saved conversation you can reopen. Each is written by someone different, stored in a different place and seen by different people. The working setup is short: rules the team needs go in the project CLAUDE.md, your own habits go in your user file, auto memory collects your corrections and you check it now and then with /memory, and the state of shared work lives somewhere outside your machine, because almost nothing Claude Code remembers leaves it. For the general kinds of memory an agent can have, see what agent memory is; this article is about making Claude Code’s own memory work across sessions.

Three things Claude Code carries forward

Anthropic’s page on how Claude remembers your project↗ (opens in a new tab) puts the starting point plainly: each session begins with a fresh context window, and two mechanisms carry knowledge across. Add the conversation itself and you have three:

• CLAUDE.md files. You write them. They load in full at the start of every session, from your user file down to the project you started in. Claude treats them as context to follow, not as enforced configuration.
• Auto memory. Claude writes it, from your corrections and preferences, one folder per repository. An index file loads at the start of each session; the notes it points to are read when needed.
• The saved conversation. claude --continue reopens the most recent conversation in the current directory and claude --resume opens a picker. Per the sessions documentation↗ (opens in a new tab), a resumed session restores the full history, including tool calls and their results.

They are not interchangeable. CLAUDE.md is what you want every session to know. Auto memory is what Claude decided was worth keeping. A resumed conversation is the raw transcript of one thread of work, useful for carrying on where you stopped and heavy for anything else.

What auto memory keeps

Auto memory is on by default. As Claude works it saves four kinds of note, recorded as a type in each file’s frontmatter: user (your role, expertise and preferences), feedback (corrections you give and approaches you confirm), project (ongoing work, deadlines and decisions it cannot get from the code or git history) and reference (where to find things outside the project, such as a dashboard or issue tracker). It deliberately skips anything it can work out from the codebase and anything your CLAUDE.md already says, and it does not save something every session.

~/.claude/projects/<project>/memory/
  MEMORY.md             # the index, one line per memory
  user_role.md          # one memory per file
  feedback_testing.md
  ...

The <project> part comes from the git repository, so every worktree and subdirectory of one repository shares a single memory. Only the first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of a session; the topic files load when Claude reads them. If the index grows past that limit, the excess is dropped on the next load, and Claude Code tells Claude to shorten it. When you see “Saved 2 memories” or “Recalled 2 memories” in the interface, that folder is being written or read.

Two details matter for keeping it honest. Claude Code stamps a modified time into the frontmatter of memory files it writes, so you and Claude can see how old a fact is. And memory files are excluded from the clean-up that deletes old session transcripts: they stay until you or Claude edit or delete them. Nothing expires on its own.

Telling Claude where a fact should go

The wording of your request decides the destination. “Remember that the API tests need a local Redis” goes to auto memory. “Add this to CLAUDE.md” goes to the instructions file. Choose on purpose:

• A rule every teammate’s session should follow: the project CLAUDE.md, committed with the code.
• A habit of yours in every project: ~/.claude/CLAUDE.md.
• A private note about one project, such as your sandbox URL: CLAUDE.local.md, kept out of git.
• A correction you would rather not curate by hand: let auto memory keep it.

Where those files sit across several repositories, and what else belongs in a repository for Claude Code, is covered in managing multiple projects with CLAUDE.md and Claude Code project structure.

Checking and pruning with /memory

/memory lists your CLAUDE.md, CLAUDE.local.md and other memory files across user and project scopes, lets you switch auto memory on or off, and opens the auto memory folder. Everything in it is plain Markdown you can read, edit or delete. /context shows which memory files actually loaded into the current session. A short routine keeps memory useful:

1. Open the folder from /memory and read MEMORY.md. It should read like a list of facts you would stand behind.
2. Delete what is no longer true. An agent acts on an out-of-date note as confidently as a current one.
3. Promote what the team needs. If a feedback memory is really a project rule, move it into the project CLAUDE.md and remove it from memory, so it is not said twice.
4. Look for anything that should not be on disk in plain text: tokens, passwords, customer details. Remove it and tell Claude not to save that kind of thing.

To turn auto memory off for one project, set "autoMemoryEnabled": false in that project’s settings; CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off through the environment, and autoMemoryDirectory moves it somewhere else.

What survives compaction and resume

Long sessions get compacted: the conversation is summarised to make room. The context window guide↗ (opens in a new tab) lists what comes back whole: the project-root CLAUDE.md, auto memory and a plan written in plan mode are re-injected from disk, while nested CLAUDE.md files and path-scoped rules reload as Claude reads matching files. An instruction you only gave in chat is summarised along with everything else, and may not survive. If it matters, write it down.

Resuming is the other half. It brings back the conversation, but not every launch option: directories added with --add-dir and servers passed with --mcp-config have to be passed again, while settings files are simply re-read. Resume is the right tool for carrying on yesterday’s thread. It is not memory in any useful sense for anyone else, because the transcript is long, unsummarised and yours alone.

Subagents can keep memory of their own

A subagent can be given its own persistent folder with a memory field in its definition. The subagent documentation↗ (opens in a new tab) offers three scopes: user in ~/.claude/agent-memory/, project in .claude/agent-memory/, which can be committed, and local in .claude/agent-memory-local/, which should not be. It recommends project as the default. The subagent reads the first 200 lines or 25KB of its own MEMORY.md at start, like the main session. Two caveats: this is part of auto memory, so turning auto memory off disables it, and the main conversation’s auto memory is not loaded into subagents, apart from forks of the conversation.

Where Claude Code’s memory stops

The documentation is explicit that auto memory is machine-local and not shared across machines or cloud environments. Your user file and CLAUDE.local.md are yours alone. The project CLAUDE.md is shared, but only through commits, and it holds instructions rather than the state of work. So a colleague’s session, Cursor on another laptop, or your own session in a cloud environment cannot see what your auto memory learned this morning.

That is fine for preferences. It is not fine for work several people or sessions depend on: which bug is being fixed, what has been tried, what was decided and by whom. That needs a record every session and every person can read, with the author of each change visible.

Shared state on a board

A fenbs board connected over MCP is one place for it. Each task keeps a note (what the problem is), a plan (how it will be done, rewritten as the agent learns) and a comment thread, and the board keeps AI context: short notes every connected assistant reads with fenbs_get_context before it starts. An assistant that learns something the next one needs can add a note with fenbs_add_context_note, signed with its name, and should change an out-of-date note with fenbs_update_context_note rather than add a contradicting one. Anyone who can see the board can read the context; changing it needs permission to change tasks. A decision recorded as a standing rule is listed in every assistant’s AI context as well.

## Memory
- Personal preferences and corrections: auto memory is fine.
- Anything another session or person needs (what is under way, what was tried,
  what was decided): write it to the board, not to memory.
- At the start of a session: fenbs_get_context with project "api".
- Before you stop: rewrite the plan on the task and comment what changed.

The split is easy to remember. Auto memory knows how you like to work. The board knows where the work stands, and the board’s history shows who changed what, including which changes an assistant made on your behalf.