Claude Code memory isn’t one feature. It’s four kinds of file, and each loads by its own rule: CLAUDE.md files you write, rules files scoped to paths, an auto memory folder Claude writes for itself, and, since recently, AGENTS.md. Most memory bugs come from the same place. The note exists, but the rule that loads it never fires, so Claude acts as if it was never written.
I run a fleet of scheduled Claude Code agents for this site, and their memory works very differently from the one on your laptop. My agents start from scratch on every run, by design. Everything they “remember” lives in plain files I can measure. On 9 November one of those files went from 10,460 lines to 8 in a single run. That’s the reason this guide spends less time on what Claude remembers and more on what it silently doesn’t load.
Every load rule below was re-checked against Anthropic’s Claude Code memory docs on 23 November 2026. Version numbers matter here, so I give them.
How Claude Code Memory Works: 4 Layers in One Table

Each session starts with an empty context window. What carries over between sessions is whatever these four layers put back in:
| Layer | Where it lives | When it loads | Size rule | Who writes it |
|---|---|---|---|---|
| CLAUDE.md (+ CLAUDE.local.md) | Managed policy path, ~/.claude/CLAUDE.md, ./CLAUDE.md or ./.claude/CLAUDE.md, subfolders | Your folder and every folder above it at launch. Subfolders load once Claude touches a file there | Loads whole up to 4 MiB. A file over 4 MiB loads nothing. The recommended size is under 200 lines | You |
.claude/rules/*.md | Project .claude/rules/ or ~/.claude/rules/ | At launch if there’s no paths: frontmatter. Otherwise when Claude reads or edits a matching file | On-demand files have a per-file character limit (see below) | You |
| Auto memory | ~/.claude/projects/<project>/memory/: a MEMORY.md index plus one topic file per memory | The first 200 lines or 25KB of MEMORY.md at start, whichever comes first. Topic files only when Claude decides to read them | Anything past the cutoff isn’t loaded | Claude |
| AGENTS.md | AGENTS.md or .claude/AGENTS.md in your folder and the ones above it | By default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists on that path. Needs v2.1.277+ | Same as CLAUDE.md | You (or the other tools you use) |
Two points from the docs come before everything else. First, Anthropic says plainly that CLAUDE.md and auto memory are context, not enforced configuration. CLAUDE.md content arrives as a user message after the system prompt, and Claude tries to follow it but nothing guarantees it will. If an action has to be blocked no matter what, use a hook, not a sentence in a memory file.
Second, files don’t override each other. Every CLAUDE.md that loads gets concatenated, from the filesystem root down to your working folder, and CLAUDE.local.md comes last at each level. If two files contradict each other, Claude may follow either one. Put “use tabs” in one file and “use spaces” in another, and you’ve created a coin flip.
To see what actually loaded, run /context all and look under Memory files. To open or create the files, use /memory. Both are in my Claude Code cheat sheet if you want the rest of the commands.
CLAUDE.md vs Auto Memory: Which One to Trust for What

These two are the layers people mix up most, and they do opposite jobs.
CLAUDE.md is your rulebook. You write it, it’s checked into the repo, and Claude reads it at the start of every session. Put the things you’d otherwise explain again every time in it: build commands, conventions, “never touch the billing folder without a plan”. If you want to know how to write one that Claude actually follows, I covered that in depth, with my own file as the example, in CLAUDE.md best practices. I won’t repeat it here.
Auto memory is Claude’s notebook. Claude writes it, it lives on your machine (not in the repo), and it’s on by default in local sessions. Claude saves four types of note and tags each one in the file’s frontmatter:
user: your role, expertise and working preferencesfeedback: corrections you gave and approaches you confirmedproject: ongoing work, deadlines and decisions it can’t work out from the code or git historyreference: where outside information lives (issue tracker, dashboard)
The docs say Claude skips anything it can work out from the codebase, and anything your CLAUDE.md already says. When it writes a memory file that has frontmatter, Claude Code stamps a modified timestamp, so you can see how fresh a note is. Memory files are also excluded from the cleanup that deletes old session transcripts. They stay until someone edits or deletes them.
The split I’d use
| If the fact is… | Put it in | Why |
|---|---|---|
| A rule the whole team must follow | Project CLAUDE.md | It’s shared through git and loads whole on every run |
| Your personal preference, in every project | ~/.claude/CLAUDE.md | Yours only, and it loads everywhere |
| Your sandbox URL or test account for one repo | CLAUDE.local.md (gitignored) | Stays out of the repo |
| Only matters for one folder or file type | .claude/rules/ with paths: | Costs no context until it’s relevant |
| Something you corrected once and don’t want to correct again | Let auto memory catch it, then promote it to CLAUDE.md if it matters | Auto memory is machine-local and capped, while CLAUDE.md is permanent |
| Must never happen | A hook or a permission deny rule | Memory is advice. Hooks are enforced |
That last row is where most people go wrong. When something you put in memory gets ignored, adding a stronger sentence doesn’t fix it. Moving the rule to a layer the client enforces does.
The 200-Line / 25KB Wall (and the 4 MiB One Nobody Mentions)

This is the part of Claude Code memory most likely to hurt you, because it fails without any error at load time.
Auto memory loads the first 200 lines or the first 25KB of MEMORY.md, whichever comes first. The rest isn’t loaded at session start. Claude Code does try to protect you. After Claude writes to MEMORY.md, Claude Code checks the file against both limits. Near a limit, it nudges Claude to shorten it: one line per entry, details moved to topic files, stale entries merged or dropped. Over a limit, the write still succeeds, but Claude gets an error telling it to rewrite the index, because everything past the line will be dropped next time.
The limit has a bit of history. In February 2026 someone opened issue #25006 asking Anthropic to document an “undocumented 200-line hard limit” on MEMORY.md. It was closed as not planned. The docs now state the limit, and the 25KB rule that sits next to it.
Most guides miss the “or 25KB” half. Long lines hit the byte limit first. I measured it on my fleet’s hand-rolled memory file (not Claude’s auto memory, more on that below). It’s 827 lines and 179,681 bytes, and the 25KB mark falls on line 143. If that file were Claude’s MEMORY.md, a session would load 143 of its 827 lines, about 14% of its bytes. The 200-line rule wouldn’t even come into play.
The other two limits
- CLAUDE.md: 4 MiB, all or nothing. A CLAUDE.md that loads at launch is delivered whole as long as it’s 4 MiB or smaller. Over that, Claude Code skips the file entirely. Not truncated, skipped. You’ll almost never hit this by hand. An agent that appends a log to its own CLAUDE.md every run will hit it eventually.
- On-demand files: a per-file character limit. Subfolder CLAUDE.md files, rules in subfolders and path-scoped rules have their own limit: 40,000 characters for a 200K context window. With a 1M window it’s 200,000 characters on Opus 4.6 and Sonnet 4.6, and 150,000 on later models. Over the limit, Claude gets the start of the file plus a note telling it to read the rest. Until it does, the later instructions aren’t in context. This applies from v2.1.309. My container runs 2.1.292, so the docs are ahead of me here.
Check whether you’re over any of these limits with plain shell commands:
wc -l -c ~/.claude/projects/*/memory/MEMORY.md # under 200 lines AND under 25,000 bytes?
wc -m path/to/subfolder/CLAUDE.md # under 40,000 chars on a 200K window?
find . -name CLAUDE.md -size +4M # anything here loads nothing
There’s one more cost that doesn’t show up as an error. Everything that does load spends context. Anthropic’s own target is under 200 lines per CLAUDE.md, because longer files “consume more context and reduce adherence”. Splitting a file into @path imports keeps it tidier, but it doesn’t save context, because imports load along with the file that imports them.

Get the AI Playbook
The playbook behind my agent fleet: what each agent loads at startup, what it must report back, and the checks that catch the silent failures. Free, and you can leave whenever you like.
AGENTS.md and .claude/rules/: The Two Layers Most Guides Skip

I read the six non-Anthropic pages ranking for this term, from Milvus, mem0, Young Leaders in Tech, MindStudio, Product Talk and Medium. None of them mentions AGENTS.md or .claude/rules/. Both are in the official docs, and both change what loads.
AGENTS.md: read natively, but only when nothing else is there
Since v2.1.277, Claude Code reads AGENTS.md by itself, so a repo set up for other coding agents works without a CLAUDE.md. The catch is the default rule. Claude reads AGENTS.md only when there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or any folder above it.
That leads to a trap the docs spell out. Your team uses AGENTS.md, and you add a gitignored CLAUDE.local.md for your own sandbox notes. From then on Claude stops reading AGENTS.md, but only for you. Your teammates see one behaviour and you see another, and nobody changed the shared file.
Your user-level ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ don’t count for that check, so they keep loading alongside AGENTS.md. To read both files on purpose, open /config and set Project instructions to claude-md-and-agents-md. Or import it explicitly with an @AGENTS.md line at the top of your CLAUDE.md, which works in every session, including the ones where native AGENTS.md support isn’t available.

⚡ GET THE AI EDGE
Weekly AI tips that actually save you time and money. No fluff, no hype — just what works.
Three more details from the docs:
AGENTS.local.md,AGENTS.override.mdand anything under.agents/are not read.InstructionsLoadedhooks don’t fire for an AGENTS.md read through the setting, only for one that a CLAUDE.md imports or symlinks to.- If you used to print AGENTS.md from a
SessionStarthook as a workaround, remove the hook. With native support you’d load it twice.
.claude/rules/: memory that costs nothing until it’s relevant
Put markdown files in .claude/rules/, one topic per file. A rule without frontmatter loads at launch, with the same priority as .claude/CLAUDE.md. A rule with a paths: list loads only when Claude reads, writes or edits a matching file:
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input
- Use the standard error shape
paths is the only frontmatter field Claude Code reads. If your YAML doesn’t parse, the rule silently loads as if it had no paths, which means every session (claude --debug shows the parse error). User-level rules in ~/.claude/rules/ load before project rules. A rule that conflicts with another doesn’t override it, so keep them consistent. This layer is the honest answer to “my CLAUDE.md is too long”. Move the instructions that matter for one folder out of the file that loads every time.
Claude Code Memory for Unattended Agents: What My 827-Line File Taught Me

All six competitor pages I read explain memory for one developer on one laptop. In that setup the failure is that Claude forgets. With scheduled agents the failure is different: a file gets cut, nobody sees it load, and every run still reports success. Here’s what my fleet actually runs on, measured on 23 November.
Receipt 1: the native memory folder has been empty for 164 days
Claude Code’s auto memory folder for this project, ~/.claude/projects/-home-agent-project/, was created on 12 June. It’s owned by root, the agent user can’t write to it, and it contains nothing, not even a memory/ subfolder. The docs give several reasons auto memory can be off. It’s off by default in self-hosted environments. A session started by another Claude Code session can’t switch it back on. And an environment variable disables it. My runs are started by a scheduler through the SDK entry point and are marked unattended. I haven’t tested which of these is the actual cause, so I won’t claim one. The effect is the same either way: 164 days of runs, zero auto memory notes. Fun detail: the run that wrote this post was told at startup that a memory folder was waiting for it. ls said otherwise.
If you run Claude Code from cron, CI or the SDK, assume auto memory is not carrying anything between runs until you’ve looked in that folder yourself.
Receipt 2: memory by rule, not by auto-load
My agents get their memory differently. Rule 1 in their CLAUDE.md says to read MEMORY.md at the start of every session, a plain file in the project that every skill appends a short entry to when it finishes. The CLAUDE.md itself is 485 lines and 29,597 bytes. That’s well over Anthropic’s 200-line target, but nowhere near 4 MiB, so it loads whole. The memory file is read with a normal file tool, so the 200-line/25KB wall doesn’t apply to it. A read has its own default page size, though. When the file was 9,888 lines, a default read reached only the top 15%. I wrote that up in the long-term memory myth.
Receipt 3: one write, 10,460 lines to 8
On 9 November one run saved its entry by replacing the file instead of appending to it. 2,421,795 bytes became 1,277. Nothing was lost, because that run had copied the file to a dated backup first. But nine later runs noticed the cut, wrote “restore is your call” in their reports, and left it, which is what they’re told to do. The nightly check graded the day 16 of 16 passed. I wrote up the guard that would have caught it in give your memory file a shrink alarm.
Two weeks later the honest status: the restore still hasn’t happened. The file grew back to 827 lines from that 8-line stub, and the five months before 9 November now live only in the backups. Meanwhile there are 585 backups of MEMORY.md and 535 of the work log, about 3 GB in total. Backups that pile up get their own problem, covered in making a cleanup rule stick.
What that adds up to
- Memory fails silently. A cut-off MEMORY.md, a skipped 4 MiB CLAUDE.md and an AGENTS.md shadowed by a stray CLAUDE.local.md all raise no error at session start. You have to measure.
- Measure the file, not the run. Exit codes and “success” lines tell you a job finished, not that the files it depends on survived.
- Unattended agents should forget on purpose. A clean context every run is a feature. Put what must carry over in small, checked files with a size limit, not in a diary that grows forever.
If you’d rather have someone who has already hit these walls set up your agents’ memory and guardrails, book an automation strategy session. We’ll go through what your agents load, what they drop, and what should be a hook instead.
How to Audit and Prune Claude Code Memory (a Monthly Checklist)

Memory rots. Notes go stale, rules start contradicting each other, and files grow past their limits. Once a month, take fifteen minutes:
- See what loads. Run
/context alland read the Memory files list. If a file you rely on isn’t there, Claude can’t see it. Subfolder CLAUDE.md files won’t be listed, because they load on demand. You’ll see aLoadedline when they do. - Open the notebook. Run
/memory, open the auto memory folder, and read MEMORY.md and the topic files. Everything is plain markdown, so edit or delete anything that’s wrong. Check themodifiedstamps for notes older than the facts they describe. - Measure the limits. MEMORY.md under 200 lines and 25KB. Each CLAUDE.md ideally under 200 lines. On-demand files under the character limit for your window. Nothing near 4 MiB.
- Run the built-in audit.
/doctor prompt-audit(v2.1.283+) checks your CLAUDE.md, CLAUDE.local.md, AGENTS.md, rules, skills, commands and subagents for outdated instructions, references to files that no longer exist, and contradictions. It proposes edits and changes nothing until you say so. - Promote, then prune. If an auto memory note keeps mattering, move it into CLAUDE.md as a rule. If a CLAUDE.md line only matters for one folder, move it to a path-scoped rule. If it must never be broken, make it a hook.
- Check after compaction. The project-root CLAUDE.md survives
/compact, because Claude re-reads it from disk. Instructions you only gave in chat don’t. If something keeps disappearing after a compact, it belongs in a file. - For unattended runs: put a size check around every append-only file. If it got smaller, restore it and alert a human. Put the check in the scheduler, not the prompt.
For the wider habits around this (plan mode, small diffs, verification), see my Claude Code best practices. If you use subagents, know that they don’t inherit the main conversation’s auto memory, except for a fork. A subagent can keep its own separate auto memory through its memory setting. More in the subagents guide.
Claude Code Memory vs Claude App Memory

If you searched this phrase and landed on Anthropic’s “Claude’s memory works everywhere” article, that’s a different product. Here’s the clean split:
| Claude Code memory | Claude app memory (chat + Cowork) | |
|---|---|---|
| Where it lives | Files on your machine (CLAUDE.md, rules, ~/.claude/projects/.../memory/) | Your Claude account, in Settings > Memory, shown as a list of topics |
| Default | Auto memory on in local sessions, off by default in self-hosted environments | On by default for Free, Pro, Max and Ultra. Team and Enterprise owners control it |
| How it’s written | You write CLAUDE.md. Claude writes MEMORY.md and topic files | Claude saves topics as you chat, or when you say “remember this” |
| Shared across | Worktrees of one repo on one machine. Not across machines | Chat and Cowork in the cloud. Cowork sessions that run locally don’t use it |
| Edit it with | /memory or any text editor | Settings > Memory > Topics |
Turning one off doesn’t affect the other. If you’re still choosing between the chat app and the desktop agent, I compared them in Claude chat vs Cowork.
Claude Code Memory FAQ

Does Claude Code remember between sessions?
Only through files. Each session starts with a fresh context window. Your CLAUDE.md files (and rules, and possibly AGENTS.md) load at the start, and if auto memory is on, the first 200 lines or 25KB of MEMORY.md load too. Nothing else carries over unless Claude goes and reads it.
Where is the Claude Code memory file?
Auto memory lives at ~/.claude/projects/<project>/memory/MEMORY.md, plus topic files next to it. The project name comes from the git repository, so every worktree shares one folder. Outside a git repo it comes from the project root. You can move it with autoMemoryDirectory in settings (an absolute path or one starting with ~/).
Can I turn auto memory off?
Yes. Use the toggle in /memory (it saves autoMemoryEnabled to your user settings), set "autoMemoryEnabled": false in a project’s settings, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. In a background session, or one started by another Claude Code session, the toggle can turn it off but not back on.
Why is Claude ignoring my CLAUDE.md?
Check that it loaded at all (/context all). Then look for a contradiction in another file, instructions too vague to verify, or built-in behaviour competing with your rule. If it must happen every time, make it a hook. For writing instructions Claude follows, see CLAUDE.md best practices.
Is “Auto Dream” a real Claude Code feature?
Some third-party pages describe a background “Auto Dream” step that consolidates memory, based on what they say is leaked source. The official memory docs page doesn’t mention it (I checked on 23 November). Treat it as unconfirmed, and don’t build on it.
Will Claude Code read my AGENTS.md?
On v2.1.277 or later, yes, if there’s no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md on the path. Otherwise import it with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config.
Does memory survive /compact?
The project-root CLAUDE.md does. Claude re-reads it from disk after compaction. Nested CLAUDE.md files and path-scoped rules reload when Claude next touches a matching file. Anything said only in chat is gone.
The Bottom Line on Claude Code Memory
Claude Code memory is four kinds of file with four loading rules, and the dangerous part is never the note you wrote. It’s the cutoff you didn’t see. Keep MEMORY.md under 200 lines and 25KB, CLAUDE.md short and specific, folder-specific rules in .claude/rules/, and anything that must never happen in a hook. If you run agents unattended, check that the memory folder actually has something in it, and measure your files every run. Mine taught me that the hard way, and the fix is still on my list, not done.

Get the AI Playbook
Every week: one real job I hand to an agent, what it costs, and what broke. No fluff, unsubscribe anytime.

📥 FREE: THE AI PLAYBOOK
The exact tools and workflows I use to run a one-person agency. 25 years of marketing experience distilled into an actionable guide. Yours free.
