Claude Code Memory: How CLAUDE.md and Auto Memory Work
Claude Code starts every session with a blank context, so it uses two kinds of memory to carry knowledge between sessions. CLAUDE.md files are instructions you write. Auto memory is notes Claude writes for itself as you work. Both load automatically at the start of each session. CLAUDE.md is for the rules you want followed every time; auto memory is for the things Claude learns along the way, such as your corrections and preferences.
I’ve run Claude Code daily across more than a dozen website projects, and my memory folder has 39 notes in it. This guide covers how both systems work, from Anthropic’s own documentation, plus a test I ran on October 29, 2026 to see when a CLAUDE.md rule actually changes Claude’s behaviour.
CLAUDE.md and auto memory at a glance
| CLAUDE.md | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What goes in it | Rules and instructions | Learnings: your corrections, preferences, project decisions |
| Where it lives | In your project (and optionally your home folder) | ~/.claude/projects/<project>/memory/ |
| What loads each session | The whole file | The first 200 lines or 25 KB of MEMORY.md |
| Shared with your team | Yes, if you commit it to git | No: it stays on your machine |
Both are context, not enforced settings. Anthropic’s memory documentation is clear that Claude reads them and tries to follow them, with no guarantee. To actually block an action, you need a hook or a permission rule instead.
Does a CLAUDE.md rule actually change anything? A test
To find out, I gave Claude Code the same small writing task in fresh sessions, three times without a CLAUDE.md and three times with a one-line rule in one. I ran two rules.
Rule 1, “bold lead-ins end with a colon”: a real rule from my own sites. Result: no difference at all. All six runs, with and without the file, wrote **Find your niche:** with the colon inside the bold, because that’s already how Claude writes.
Rule 2, “use British English spelling”: this goes against the model’s default.
| American spellings | British spellings | |
|---|---|---|
| No CLAUDE.md (3 runs) | 12 | 0 |
| One-line CLAUDE.md rule (3 runs) | 0 | 26 |
“Color”, “flavor” and “organize” turned into “colour”, “flavour” and “organise” every time the file was present, and never when it wasn’t. The lesson: a CLAUDE.md earns its place with instructions Claude wouldn’t follow on its own, such as your build command, a file that must never be edited, or a house style that differs from the default. Lines that restate what Claude already does just use up space.
Where CLAUDE.md files go
| File | Location | Use it for |
|---|---|---|
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
Build and test commands, project rules. Commit it so your team gets it |
| Local | ./CLAUDE.local.md |
Your personal notes for this project. Add it to .gitignore |
| User | ~/.claude/CLAUDE.md |
Preferences for every project on your machine |
| Rules folder | ./.claude/rules/*.md |
One topic per file; can be limited to certain file paths |
| Managed | A system folder set by IT | Company-wide rules that individuals can’t exclude |
Claude Code loads every CLAUDE.md and CLAUDE.local.md from the folder you start it in and every folder above it. They don’t override each other; they’re joined together, with the file closest to your working folder read last. Files in subfolders load later, when Claude first works with a file in that subfolder. If your project already uses an AGENTS.md file for other coding tools, Claude Code reads that instead when there’s no CLAUDE.md.
A CLAUDE.md can pull in other files with @path/to/file, up to four levels deep. That helps organise a long file but doesn’t save space: imported files load along with the file that imports them.
Writing a CLAUDE.md that works
The fastest start is /init inside a session. Claude reads your project and writes a first CLAUDE.md with the build commands, tests and conventions it can find. Then edit it, keeping to Anthropic’s advice and what my test showed:
- Keep it under 200 lines: Anthropic’s guidance. Longer files take up more context and get followed less reliably.
- Be specific: “Run
python build.pythenpython scripts/audit.py; the audit must print ALL CLEAN” beats “make sure everything works”. - Write down what Claude can’t discover: files that are generated and must not be edited by hand, the real build script when an old one is still lying around, where the data comes from.
- Remove contradictions: if two lines disagree, Claude may pick either.
- Skip the defaults: as the colon test showed, restating normal behaviour adds nothing.
A short example for a static website project:
# Project rules
- Pages in public/ are generated by build.py. Never edit them by hand.
- After any change: python build.py, then python scripts/audit.py (must print ALL CLEAN).
- Every number on a page comes from assets/calc.js. Never type a figure into page text.
- Use British English spelling.How auto memory works
Auto memory is on by default in local sessions. As you work, Claude saves short notes in four types, according to Anthropic’s docs: user (your role and preferences), feedback (corrections you give and approaches you confirm), project (ongoing work and decisions that aren’t in the code) and reference (where to find things outside the project). It skips anything it could work out from the code itself.
Each note is its own small file, and a MEMORY.md index lists them one line each. Only the index loads at the start of a session: the first 200 lines or 25 KB, whichever comes first. Claude opens the individual notes when it needs them. Mine currently has 39 notes and a 38-line, 5.9 KB index, well inside the limit. Typical entries are things like “bold lead-ins end with a colon on every site” and “this site’s old build script is stale; never run it”, which are exactly the corrections I’d otherwise repeat every session.
When you see “Saved 2 memories” or “Recalled 2 memories” in Claude Code, that’s auto memory working. To see or edit everything, run /memory, which lists the loaded CLAUDE.md files and opens the memory folder. The same screen has the switch to turn auto memory off. You can also set "autoMemoryEnabled": false in a project’s settings, or the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
The catch I hit: memory follows the repository, not the topic
Auto memory is stored per git repository: every subfolder and worktree of the same repo shares one memory folder. Outside a git repo, the project folder decides it. I usually start Claude Code from one website’s folder, which is a git repo, and then work on other sites from there. The result is that notes for about 30 different sites all live in that one project’s memory, under a folder named after the tip-calculator repo.
It works, because Claude finds the right note through the index, but it’s not what you’d design. If you work on several projects, start Claude Code inside each project’s own folder, so each gets its own memory. Also keep in mind that auto memory is machine-local. It doesn’t sync to another computer or to cloud sessions, so anything your team needs belongs in a committed CLAUDE.md.
Keep memory honest
Old notes can mislead. A memory that says “the build script is build.js” stays true in Claude’s mind long after you switched to build.py. A few habits help:
- Correct it out loud: when Claude acts on an outdated note, tell it, and ask it to update or delete that memory.
- Read the index now and then: open
/memory, skimMEMORY.md, and remove what’s no longer true. - Promote stable rules: once a learned preference is permanent, move it into CLAUDE.md, where the whole team gets it and you control the wording.
- Remember subagents start fresh: Anthropic’s docs note that the main session’s auto memory isn’t loaded into subagents (forks are the exception), so give a subagent the rules it needs in its own instructions.
When instructions aren’t being followed
Run /context and look under Memory files to confirm your CLAUDE.md actually loaded. A CLAUDE.md in a subfolder won’t appear there until Claude touches a file in that folder. Then check the rule itself: is it specific, does anything contradict it, and is the file under 200 lines? If a rule must never be broken, such as “never delete this folder”, use a hook or a permission setting, because memory files are guidance, not locks.
New to Claude Code? Start with how to install Claude Code, which ends with running /init to create your first CLAUDE.md. For how project instruction files compare across Cursor, Copilot and Codex, see our AI coding tools comparison. Our calculator website case study shows the kind of rules worth writing down.
Common questions
Does Claude Code remember previous conversations? Not the conversations themselves. Each session starts with a fresh context. What carries over is your CLAUDE.md files and the auto memory notes Claude saved. You can also resume a recent session with claude --continue or claude --resume.
Where is Claude Code memory stored? CLAUDE.md files live in your project or in ~/.claude/CLAUDE.md. Auto memory lives in ~/.claude/projects/<project>/memory/, with a MEMORY.md index and one file per note.
How do I clear or reset it? Edit or delete the files. Open /memory to find them, remove the notes you don’t want, and update the matching lines in MEMORY.md. Deleting a CLAUDE.md removes those instructions from future sessions.
Is there a size limit? Only the first 200 lines or 25 KB of MEMORY.md load at the start of a session. For CLAUDE.md, Anthropic recommends staying under 200 lines so instructions are followed reliably.
