Blog
Published: October 28, 2026
Claude Code auto memory is the set of notes Claude writes for itself as it works: your corrections, your preferences, and project facts the code does not show. It is on by default. The notes live in ~/.claude/projects/<project>/memory/, and the first 200 lines or 25KB of its MEMORY.md index load at the start of every session. Turn it off with the /memory toggle, autoMemoryEnabled: false in settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Everything below was checked against Anthropic's memory docs and the changelog through v2.1.312 on 28 October 2026.
Does Claude Code have memory across sessions? #
Yes, two kinds. Every session starts with a fresh context window, and two things carry over: CLAUDE.md files, which you write, and auto memory, which Claude writes. The conversation itself does not carry over unless you go back to it with /resume. Auto memory arrived in v2.1.32 (“Claude now automatically records and recalls memories as it works”) and is on by default in local sessions.
MEMORY.md vs CLAUDE.md: what is the difference? #
| CLAUDE.md | Auto memory (MEMORY.md) | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns |
| Scope | Project, user or organization | One repository on one machine, shared across its worktrees |
| What loads | The whole file at launch, up to 4 MiB | The first 200 lines or 25KB of MEMORY.md |
| Who sees it | Whoever gets the file, often the team through git | Only you |
Claude files each note under one of four types in its frontmatter: user (your role and preferences), feedback (corrections and approaches you confirmed), project (work, deadlines and decisions the code cannot show) and reference (where to look outside the repo). It skips what it can read from the code and what your CLAUDE.md already says, and it does not save something every session. Ask it to remember something and it goes to auto memory; say “add this to CLAUDE.md” to put it in the file instead. The docs treat both as context, not enforced configuration.
Where does Claude Code store memory? #
In ~/.claude/projects/<project>/memory/. The <project> part comes from the git repository, so every subfolder and worktree of one repo shares one folder (since v2.1.63). Outside a git repo, the project root is used. Inside are MEMORY.md, an index with one line per memory that loads into every session, and one topic file per memory, such as feedback_testing.md, which Claude reads only when it needs it.
To keep it somewhere else, set autoMemoryDirectory to an absolute or ~/ path (settings reference, added in v2.1.74). Set in a repo's own settings files, it is honored only once you trust the folder. Memory files never expire: the cleanupPeriodDays sweep that deletes old transcripts skips them, so they stay until you or Claude edits or deletes them.
How much of MEMORY.md does Claude Code load? #
The first 200 lines or the first 25KB, whichever comes first (the 25KB cap came in v2.1.83). Anything past that is not loaded at session start. Near the limit, Claude Code reminds Claude to shorten the index: one line per entry, detail in topic files, stale entries merged or dropped. Since v2.1.210 a write that leaves it over the limit returns an explicit error; before that the end was cut silently. The limit is only for MEMORY.md. A CLAUDE.md that loads at launch arrives whole, up to 4 MiB.
Is Claude Code auto memory on or off by default? #
On, in local sessions. A session in a self-hosted environment runs with it off by default, and --bare (or CLAUDE_CODE_SIMPLE=1) skips it with the rest of auto-discovery. To switch it:
-
For you, everywhere. Open
/memoryand flip the auto memory toggle. It writesautoMemoryEnabledto~/.claude/settings.json. -
For one project. Put
{ "autoMemoryEnabled": false }in that project's settings. -
For one session.
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1turns it off;=0forces it on even over the setting or--bare(environment variables ). Since v2.1.285 the toggle cannot turn it back on from a background session or from a session one of Claude Code's own tools started. It reads “off · can't be turned on here”: runclaudein your terminal and flip it there.
How do I see, edit or clear Claude Code memory? #
Run /memory and choose the auto memory folder. Every note is plain markdown you can read, edit or delete; delete a topic file and its line in MEMORY.md to make Claude forget one thing. When Claude Code says “Saved 2 memories” or “Recalled 2 memories”, it is writing to or reading from that folder. To see what loaded into the current session, run /context. In VS Code, the Customize menu has a Memory entry with the same toggle and folders (v2.1.274).
Why is Claude Code auto memory not working? #
- It is off for this session. A setting, the environment variable,
--bare, a background session or a self-hosted environment. - Claude chose not to save it. It skips what the code or your
CLAUDE.mdalready says. Ask it to remember the thing explicitly. - The note is past line 200 of the index. Only the start of
MEMORY.mdloads, and a topic file loads only when Claude decides to read it. - A subagent did the work. The main conversation's auto memory is not loaded into subagents, except a fork.
- You are on another machine or in the cloud. The files are not shared across machines or cloud environments.
- A project picked the folder. An
autoMemoryDirectoryfrom repo settings needs trust, and withpermissions.blockReadsOutsideWorkingDirectorieson, Claude Code neither loads nor saves there. - It was stale right after compaction. Before v2.1.311, Claude could see old
MEMORY.mdcontent right after an automatic compaction. Update.
If the problem is a CLAUDE.md rule rather than a memory, see why Claude ignores CLAUDE.md.
What happens to memory when Claude Code compacts? #
It comes back. After /compact or an automatic compaction, auto memory and the project-root CLAUDE.md are re-injected from disk (what survives compaction). What does not come back is anything said only in the conversation: it is summarized with the rest. Path-scoped rules and nested CLAUDE.md files reload when Claude touches a matching file again. /clear starts an empty conversation and keeps project memory, so the next message starts like a new session.
Do subagents have their own memory? #
Only if you give them one. A memory field in the subagent's frontmatter (since v2.1.33) gives it a folder and loads the first 200 lines or 25KB of its own MEMORY.md (subagent docs). Turn auto memory off and the field does nothing:
| Scope | Folder | Use when |
|---|---|---|
user |
~/.claude/agent-memory/<name>/ |
It should learn across all your projects |
project |
.claude/agent-memory/<name>/ |
Its notes belong to the repo and can be committed |
local |
.claude/agent-memory-local/<name>/ |
Its notes belong to the repo but stay out of git |
What is Claude Code auto dream? #
Not a documented feature. Third-party posts from March 2026 describe a background pass by that name that tidies the memory folder, and a /dream command, but Anthropic's command list, memory docs and changelog through v2.1.312 do not mention either. What Claude Code does document is the upkeep above: the reminder to shorten the index, the error when it runs over, and a modified timestamp in each memory's frontmatter (v2.1.214) so Claude can tell fresh notes from stale ones.
Who else can see my auto memory? #
Nobody. “Auto memory is machine-local”, so a teammate's Claude never reads what yours learned, and neither does yours on your laptop if it learned on your desktop. Other agents keep their own: see Codex memories, GitHub Copilot Memory and what happened to Cursor Memories, or all four side by side in Claude Code memory vs Codex, Cursor and Copilot. What a team can share today is in Claude Code team memory.
When a memory should become a rule #
A note in auto memory helps one person on one machine. If the correction matters to everyone, write it into CLAUDE.md or .claude/rules/ in the pull request that needed it; how to make Claude Code remember your corrections walks through it.
Or use a memory the whole team's agents read. Harbor is one: shared memory for AI coding agents. It learns from where your team decides (Slack, pull request reviews, docs and agent sessions), lets you set what waits for a person, and gives Claude Code, Cursor, Codex and GitHub Copilot the rules that apply to each task.
Questions #
Where does Claude Code store auto memory?
In ~/.claude/projects/<project>/memory/, where <project> comes from the git repository, so every worktree and subfolder of one repo shares the folder. It holds a MEMORY.md index and one markdown file per memory. Set autoMemoryDirectory in settings to keep it somewhere else.
How do I turn off Claude Code auto memory?
Flip the auto memory toggle in /memory, which writes autoMemoryEnabled to ~/.claude/settings.json. For one project, set "autoMemoryEnabled": false in its settings. For one session, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. It is on by default in local sessions (Claude Code v2.1.312, 28 October 2026).
What is the difference between MEMORY.md and CLAUDE.md?
You write CLAUDE.md: instructions and rules, loaded whole, often shared with the team through git. Claude writes MEMORY.md: an index of notes it took from your corrections and preferences, kept on your machine only, with the first 200 lines or 25KB loaded each session.
Does auto memory survive /compact and /clear?
Yes. After a compaction Claude Code re-injects auto memory and the project-root CLAUDE.md from disk; only what was said in the conversation is summarized away. /clear starts an empty conversation and keeps project memory.
Is Claude Code auto dream a real feature?
Not a documented one. As of 28 October 2026, Anthropic's command list, memory docs and changelog through v2.1.312 do not mention auto dream or a /dream command; only third-party posts do. Claude Code does remind Claude to shorten MEMORY.md near its 200-line limit.