CLAUDE.md 与记忆系统

一句话定位：Claude Code 的记忆分两层加一条兜底——CLAUDE.md 是你写的持久指令，auto memory 是它自己记的笔记，上下文满了自动压缩兜底；本文讲每层装什么、多大开始变成负资产。前置：Claude Code 全景与日常使用——知道上下文窗口与自动压缩的产品行为。

先从反复教同一件事说起

你和 Claude Code 合作了两周，项目约定教过它好几遍：测试用哪个命令、提交前跑什么检查、目录怎么组织。它会照做，你也满意。

直到某天你发现：每次新会话，这些约定都要从头再教。上下文窗口一关，一切清零——它不是不听话，是根本不记得。把约定贴进对话？下个会话就丢。全写进一个说明文件？听说文件越长它越不听话。让它自己记？记在哪、记什么、什么时候会忘？

这个产品的记忆系统到底怎么分层——什么该你写、什么它自己记、什么靠压缩续命？

官方的答案是「两层加一条兜底」：CLAUDE.md 是你写的持久指令，每次会话开场必载；auto memory 是 Claude 给自己记的笔记，一个索引加一堆主题文件、按需取用；上下文满了由自动压缩兜底——那是上一章讲过的产品行为，本章只说它在记忆版图里的位置。先看全景：

图：记忆分层——①你写的 CLAUDE.md 四级作用域 ②它记的 auto memory ③每场会话的上下文窗口；自动压缩在③里兜底

渐进拆解：一个新员工的两份手册

类比：把 Claude Code 想成一位每早都「失忆重来」的资深同事。CLAUDE.md 是你给 TA 的工作手册——入职第一天就摆在桌上，每天都要读一遍；auto memory 是 TA 自己的笔记本——你纠正一次 TA 记一条，下次先翻笔记再干活；自动压缩则是工位太小时的整理术——旧文件装箱收进柜子，桌面只留正在办的。三样各管一段，别让一本手册越写越厚，也别指望笔记本替你定规矩。

CLAUDE.md：你写的那份手册（①）

它就是个 markdown 文件，放在约定位置、每次会话开场自动载入。四级作用域从宽到窄：

• 企业策略：IT 统一下发，管全公司合规。
• 用户级：~/.claude/CLAUDE.md，你的个人偏好跟人走。
• 项目级：./CLAUDE.md 或 ./.claude/CLAUDE.md，入库随 git 共享给全组。
• 本地级：CLAUDE.local.md，进 .gitignore，只属于你在这台机器的这个项目。

加载规则两条：

• 从当前目录逐级向上，每一级的都算数——在 foo/bar/ 里启动，foo/bar/ 与 foo/ 的 CLAUDE.md 都会载入。
• 子目录里的按需加载——读到那个目录的文件，才载入对应指令。

官方给的写法判据一句话：只写「每个会话都该知道」的事实——构建命令、约定、项目结构、「永远要 X」类规则。多步骤流程与只跟某类文件相关的指令，分别归 Skills（按需加载的技能包）与路径作用域规则（放 .claude/rules/ 下、路径匹配才加载的规则文件）。

写法四原则（官方口径）

• 尺寸：单文件以 200 行内为目标——文件越长，占上下文越多、遵循度越低。
• 结构：用标题与分组，Claude 扫结构和人一样。
• 具体到可验证：「用两空格缩进」好过「把代码格式化好」，「提交前跑 npm test」好过「记得测试」。
• 一致性最要紧：两条规则互相矛盾时，Claude 可能随机挑一条遵循。

文件之间用 @路径 导入拆分组织（相对路径按所在文件解析，最多递归四层），但导入的文件开场照样进上下文——拆分是整理，不是瘦身。

auto memory：它自己记的笔记（②）

这是「你不用动手」的那一层：默认开启，Claude 在会话中根据你的纠正与偏好自动写笔记。存储按仓库隔离（同仓库的所有子目录与工作树共享一份），位置在用户目录的项目缓存下；结构是一本 MEMORY.md 索引加若干主题文件——每条记忆一个文件，索引一行一条：

• 开场只载索引的前 200 行（或 25KB，先到为准）。
• 主题文件不进开场，要用时按需读取。

索引快超限时产品会提醒它精简，超了就报错逼它重写。这套「索引薄、细节下沉」的设计正是 Context 工程说的预算花法。会话里看到「Saved 2 memories」就是它在写，/memory 随时翻看编辑——笔记是明文 markdown，删改随意。另有一个值得知道的隔离：主对话的 auto memory 不进子代理（受派干活的独立 Agent 实例）的上下文，子代理可以配自己的独立笔记目录——脏活的上下文，不污染主笔记。

自动压缩：工位整理术（③）

上一章说过，上下文满员前自动压缩兜底——在记忆版图里，它是「会话内」的机制：压缩的是对话历史，不碰 CLAUDE.md 与 auto memory 这两个仓库。三层的分工由此清晰：约定进手册，纠正进笔记，过程靠压缩——别把该进手册的东西塞给压缩去「记」。

大白话：约定写手册，纠正记笔记，聊天靠压缩。手册你写、它每天读；笔记它写、你自己删；压缩产品做、你不用管。三件事别互相顶班——手册越写越厚、笔记没人清理、压缩被当成记忆，都是乱岗的开始。

技术定义：CLAUDE.md 是会话启动时自动载入上下文的 markdown 指令文件：四级作用域、逐级向上加载、子目录按需，支持 @路径 导入。auto memory 是按仓库隔离的自动笔记：MEMORY.md 索引开场载入、主题文件按需读取，仅本机有效。自动压缩在上下文将满时替换对话历史，不触碰两个持久仓库。

动手：给项目配一份及格的 CLAUDE.md

进入会话后，三条斜杠命令起步（# 后是注解）：

/init                        # 扫描代码库，生成一份起步 CLAUDE.md
/context                     # 查看本次会话载入了哪些记忆文件、各占多少
/memory                      # 浏览与编辑 CLAUDE.md 和 auto memory 的各文件

/init 生成的是底子，价值在于你接着补「它自己发现不了的」约定。一份及格的项目级 CLAUDE.md 长这样（节选，伪示例不可直接运行）：

# 项目约定
## 命令
- 测试：npm test（提交前必跑，失败不得提交）
- 本地启动：npm run dev，端口 4399
## 结构
- API 处理器一律放 src/api/handlers/
## 风格
- 缩进两空格；组件命名用大驼峰

注意每条都具体可验证。反面教材：「保持代码整洁」「认真测试」——这类句子占上下文却不产生遵循度。写完跑一次 /context，看到自己的文件列在 Memory files 里才算生效；之后每教一次新约定，就顺手补进对应层级，而不是在对话里重发一遍。

三种记忆去处一张表对齐（口径来自官方文档）：

边界与取舍：手册写到多厚算负资产

CLAUDE.md 不是配置，是上下文

官方文档特别提醒：它是「喂给模型的上下文，不是强制执行的配置」——模型遵循得再好也是概率行为。需要确定性的事（提交前必须跑 lint、某文件不许动），别指望手册里一句话，那是 Hooks 的地盘：事件驱动的脚本，物理上拦得住。

那一条指令来了，到底放哪？官方的分流逻辑三问定去处：

图：指令分流——每个会话都要的进 CLAUDE.md，路径相关的进规则，多步骤的进 Skill，偏好与纠正交给 auto memory 自己记

负资产的判断信号

官方给的是阈值：单文件 200 行内为目标，4 MiB 是载入硬上限。但真正的信号是行为不是行数：

1. 你发现自己超过两周没读过这个文件，它多半已经堆满过期规则。
2. 同一件事文件里说法与你的口头纠正不一致——矛盾规则会被随机遵循。
3. 某些规则只跟个别目录相关却全局常驻——那是路径作用域规则的活。
4. /context 里记忆文件占比挤占了干活空间。

处理顺序：删过期的、下沉路径相关的、拆导入组织的——压缩手册厚度，别压缩遵循度。

monorepo 还有一档官方解法：别的团队塞在仓库里的 CLAUDE.md，可以用 claudeMdExcludes 配置整体排除，不让它进你的会话。

auto memory 不是真理库

它记的是「Claude 理解的你的偏好」，会记错也会过时；跨机器不共享（按仓库、按本机隔离）。定期 /memory 翻看，删掉与现状不符的条目——就像你也会纠正一个新同事的笔记。产品行为的机制层对照：自动压缩对应手写 Harness 里的上下文压缩机构，CLAUDE.md 对应常驻上下文的组装（预算与装窗的机制在 Context 工程），auto memory 对应文件式长期记忆——Harness 记忆系统一篇讲后者的三级结构与召回管线。

自测

合上文章先自己答，再展开对照：

参考与延伸

• Claude Code 官方文档《How Claude remembers your project》：CLAUDE.md 作用域、加载规则、写法原则与 auto memory 机制的原始出处 — code.claude.com/docs/en/memory
• 《Context window》：上下文窗口可视化，看记忆文件在启动上下文中的位置 — code.claude.com/docs/en/context-window

下一站：Skills 实战：从斜杠命令到渐进披露——手册放不下的多步骤流程，封装成按需加载的技能包。