How Claude Code remembers across sessions
Every Claude Code session starts with an empty context window; the conversation itself does not carry over. Two things do: the CLAUDE.md files you write (with the files they import) and auto memory, the notes Claude writes for itself in a folder per repository. Both load at the start of every session, so the more they hold, the more every turn costs.
Updated 2026-11-16
What carries over and what does not#
| Carries over? | Who writes it | When it loads | |
|---|---|---|---|
| The conversation | No. A new session starts empty. /resume reopens an old one, which is a different thing from memory. | You and Claude | Only while the session runs |
| CLAUDE.md files | Yes | You | At launch, every session |
Files a CLAUDE.md imports with @path | Yes | You | At launch, with the file that imports them |
.claude/rules/*.md | Yes | You | At launch; a rule with a paths field loads when Claude touches a matching file |
| Auto memory | Yes | Claude | At launch: the start of MEMORY.md; topic files when Claude opens them |
| A CLAUDE.md in a subfolder | Yes | You | On demand, once Claude works in that subfolder |
Source: Anthropic’s memory docs. Claude treats all of it as context, not as enforced rules: an instruction it must never skip belongs in a hook, not a memory file.
CLAUDE.md: the memory you write#
CLAUDE.md files load in a fixed order, broadest first, so a project instruction lands after a user instruction:
- Managed policy, set by an organization:
/Library/Application Support/ClaudeCode/CLAUDE.mdon macOS,/etc/claude-code/CLAUDE.mdon Linux,C:\Program Files\ClaudeCode\CLAUDE.mdon Windows. - Your user file,
~/.claude/CLAUDE.md: loads in every project. - The project file,
./CLAUDE.mdor./.claude/CLAUDE.md, shared through git. A repository can useAGENTS.mdin its place. ./CLAUDE.local.md: your own notes for one project, kept out of git.
A line like @docs/testing.md imports that file at launch, and an imported file can import more, up to four hops deep. An import is never on demand: it loads every session, with the file that names it. A path in backticks stays text and is not imported.
To see what loaded, run /context all and read the list under Memory files. /memory opens the files for editing.
Auto memory: the memory Claude writes#
As it works, Claude saves notes for itself: your role and preferences, corrections you gave it, project decisions it cannot read from the code, and pointers to things outside the repo. It skips what the code already says and what your CLAUDE.md already covers.
The notes live in one folder per repository, ~/.claude/projects/<project>/memory/, with MEMORY.md as the index and one topic file per note. All worktrees and subfolders of a repository share that folder; it is machine-local and never shared across machines. The start of MEMORY.md loads in every session; the topic files are read when a task needs them.
Auto memory is on by default in a local session. /memory has a toggle, which writes autoMemoryEnabled to ~/.claude/settings.json; a project can set it to false in its own settings, and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off everywhere. autoMemoryDirectory in settings moves the folder.
The paths, with what MinniMemoryMCP adds beside them, are listed in Where Claude Code keeps its memory.
Why memory that carries over costs tokens#
Everything in the first two rows of the table above is sent with every turn, not once per session: each turn re-sends the whole conversation, and the memory files are at the front of it. A CLAUDE.md that grew from twenty lines to four hundred, plus three imported files, is paid for on every turn of every session, whether or not the task touches it.
The fix is the same one Anthropic’s own docs describe for large projects: keep in the always-loaded part only what every turn needs, and move the rest to files that load on demand. MinniMemoryMCP makes that split and keeps it current: a small AlwaysOnMemory part plus OnDemandMemory files, every line kept, undo to go back.
$ npm i -g minnimemory
$ minnimemory installWith MinniMemoryMCP 1.6.0 on our test memory, the agent went looking in its memory 17 times instead of 89 over the same 87 answers, and the run used 47.2% fewer tokens.
How the split is made, by hand or with the tool, is in Claude Code memory: CLAUDE.md vs MinniMemoryMCP. What a session costs turn by turn is in Why Claude Code sessions get expensive.