| |

克勞德代碼記憶,由一位特工故意遺忘的人解釋:CLAUDE.md、自動記憶、AGENTS.md 和 200 行牆

克勞德代碼記憶

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:

層Where it livesWhen it loadsSize ruleWho writes it
CLAUDE.md (+ CLAUDE.local.md)Managed policy path, ~/.claude/CLAUDE.md, ./CLAUDE.md 或者 ./.claude/CLAUDE.md, subfoldersYour folder and every folder above it at launch. Subfolders load once Claude touches a file thereLoads whole up to 4 MiB. A file over 4 MiB loads nothing. The recommended size is under 200 linesYou
.claude/rules/*.md專案 .claude/規則/ 或者 ~/.claude/rules/At launch if there’s no 路徑: frontmatter. Otherwise when Claude reads or edits a matching fileOn-demand files have a per-file character limit (see below)You
Auto memory~/.claude/projects/<project>/memory/: a 記憶體.md index plus one topic file per memoryThe first 200 lines 或者 25KB of MEMORY.md at start, whichever comes first. Topic files only when Claude decides to read themAnything past the cutoff isn’t loaded克勞德
代理商.md代理商.md 或者 .claude/AGENTS.md in your folder and the ones above itBy default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists on that path. Needs v2.1.277+Same as CLAUDE.mdYou (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 /記憶. Both are in my 克勞德代碼作弊表 if you want the rest of the commands.

CLAUDE.md vs Auto Memory: Which One to Trust for What

CLAUDE.md written rules versus Claude Code auto memory notes

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 如何 to write one that Claude actually follows, I covered that in depth, with my own file as the example, in CLAUDE.md 最佳實踐. 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 preferences
  • feedback: corrections you gave and approaches you confirmed
  • project: ongoing work, deadlines and decisions it can’t work out from the code or git history
  • 參考: 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 修改的 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為什麼
A rule the whole team must followProject CLAUDE.mdIt’s shared through git and loads whole on every run
Your personal preference, in every project~/.claude/CLAUDE.mdYours only, and it loads everywhere
Your sandbox URL or test account for one repoCLAUDE.local.md (gitignored)Stays out of the repo
Only matters for one folder or file type.claude/規則/ 和 路徑:Costs no context until it’s relevant
Something you corrected once and don’t want to correct againLet auto memory catch it, then promote it to CLAUDE.md if it mattersAuto memory is machine-local and capped, while CLAUDE.md is permanent
Must never happenA hook or a permission deny ruleMemory 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)

Claude Code memory 200 line and 25KB load limit

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 @小路 imports keeps it tidier, but it doesn’t save context, because imports load along with the file that imports them.

潛在客戶開發人工智慧策略手冊,營運商的人工智慧自動化策略手冊

取得人工智慧策略手冊

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.

引流工具 - AI 策略手冊

AGENTS.md and .claude/rules/: The Two Layers Most Guides Skip

AGENTS.md and .claude/rules in Claude Code memory

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/規則/. 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 代理商.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/規則/ 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 到 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.

喬恩瓊斯

⚡ 取得人工智慧優勢

每週提供真正省時省錢的AI小技巧。沒有廢話,沒有誇大其詞——只有切實有效的方法。.

訂閱電子報 - 部落格行動號召

Three more details from the docs:

  • AGENTS.local.md, AGENTS.override.md and anything under .agents/ 是 不是 read.
  • InstructionsLoaded hooks 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 會話開始 hook 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/規則/, one topic per file. A rule without frontmatter loads at launch, with the same priority as .claude/CLAUDE.md. A rule with a 路徑: 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

Claude Code memory file truncated in an unattended agent fleet

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 不是 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

  1. 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.
  2. Measure the file, not the run. Exit codes and “success” lines tell you a job finished, not that the files it depends on survived.
  3. 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, 預約自動化策略會議. 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)

Auditing and pruning Claude Code memory files

Memory rots. Notes go stale, rules start contradicting each other, and files grow past their limits. Once a month, take fifteen minutes:

  1. See what loads. 跑步 /context all and 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 a Loaded line when they do.
  2. Open the notebook. 跑步 /記憶, 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 the 修改的 stamps for notes older than the facts they describe.
  3. Measure the limits. MEMORY.md under 200 lines 和 25KB. Each CLAUDE.md ideally under 200 lines. On-demand files under the character limit for your window. Nothing near 4 MiB.
  4. 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.
  5. 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.
  6. Check after compaction. The project-root CLAUDE.md survives /袖珍的, 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.
  7. 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 克勞德代碼最佳實踐. If you use subagents, know that they 不 inherit the main conversation’s auto memory, except for a fork. A subagent can keep its own separate auto memory through its 記憶 setting. More in the subagents guide.

Claude Code Memory vs Claude App Memory

Claude Code memory compared with 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 memoryClaude app memory (chat + Cowork)
Where it livesFiles on your machine (CLAUDE.md, rules, ~/.claude/projects/.../memory/)Your Claude account, in Settings > Memory, shown as a list of topics
DefaultAuto memory on in local sessions, off by default in self-hosted environmentsOn by default for Free, Pro, Max and Ultra. Team and Enterprise owners control it
How it’s writtenYou write CLAUDE.md. Claude writes MEMORY.md and topic filesClaude saves topics as you chat, or when you say “remember this”
Shared acrossWorktrees of one repo on one machine. Not across machinesChat and Cowork in the cloud. Cowork sessions that run locally don’t use it
Edit it with/記憶 or any text editorSettings > 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

Claude Code memory frequently asked questions

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 /記憶 (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 最佳實踐.

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 在 /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 和 25KB, CLAUDE.md short and specific, folder-specific rules in .claude/規則/, 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.

潛在客戶開發人工智慧策略手冊,營運商的人工智慧自動化策略手冊

取得人工智慧策略手冊

每週:我交給經紀人的一個真實項目,費用是多少,以及哪些環節出了問題。絕無廢話,隨時可以取消訂閱。.

引流工具 - AI 策略手冊
人工智慧行動指南-免費下載

📥 免費:《人工智慧劇本》

我用來經營一人代理公司的所有工具和工作流程。 25 年的行銷經驗濃縮成一份實用指南。免費贈送。.

引流工具 - AI 策略手冊

相關文章

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *