把「记忆」拆成两个独立机制，是 Claude Code 在长期协作中不掉链子的核心设计：CLAUDE.md 代表人写的、可控的、显式的指令；Auto Memory 代表模型自己总结的、隐式的、带筛选机制的学习笔记。两者的生命周期、写入主体与持久化位置完全不同，混用会让团队既丢失规范也丢失上下文。
一、两类记忆的总体差异
Claude Code 的每个会话都从一个全新的上下文窗口起步，因此必须借助「会话间持久化」机制才能跨会话保留知识。官方同时提供 CLAUDE.md 文件体系与 Auto Memory 目录体系，两者在多个维度形成对照。
| 维度 | CLAUDE.md | Auto Memory |
|---|---|---|
| 写入主体 | 开发者或团队成员 | Claude 自身 |
| 内容性质 | 显式指令与规则 | 习得的经验与模式 |
| 加载时机 | 每个会话开始时全量加载 | MEMORY.md 索引每会话加载，详细文件按需读取 |
| 容量限制 | 单文件约 200 行（更短更易遵守） | MEMORY.md 索引 200 行 / 25KB 二选一即截断 |
| 作用域 | 项目 / 用户 / 组织 / 本地 | 仓库级别（按 git 根目录派生目录） |
| 共享方式 | 项目级可提交 git 共享 | 本机私有，不跨机器同步 |
| 控制粒度 | 完全由人撰写与维护 | Claude 决定写什么，开发者事后可审计 |
把这两类机制放在一起看：CLAUDE.md 像是「公司章程」，Auto Memory 像是「员工私人笔记本」——前者是显式契约，后者是经验沉淀。
二、生命周期：写入、加载与失效
2.1 CLAUDE.md：人工写入、整文件加载
CLAUDE.md 的生命周期完全由人控制。开发者根据团队约定把「构建命令、命名规范、架构决策、必须遵守的流程」写入文件，提交到 git。Claude Code 在每个会话开始时，会沿着工作目录向上扫描，逐层加载用户级、项目级、本地级与管理级的 CLAUDE.md，顺序决定优先级，靠近工作目录的文件覆盖更广作用域的文件。
写入动作可以手动编辑，也可以通过 /init 命令让 Claude 扫描代码库生成初稿。读取动作在每个会话启动时静态完成，会话期间不会重新加载。失效方式很简单：要么人工修改文件，要么删除文件，模型不参与判断。
2.2 Auto Memory：模型写入、索引加载
Auto Memory 的生命周期以模型为驱动。Claude 在会话中观察到「这条信息对将来有用」（比如某条构建命令、某个用户偏好、某个调试经验），会写入本地目录 ~/.claude/projects/<repo>/memory/。目录结构是：一个 MEMORY.md 索引文件，加上若干按主题拆分的主题文件（如 debugging.md、api-conventions.md）。
加载逻辑分两层：MEMORY.md 在每个会话开始时被自动加载，截断阈值是 200 行或 25KB（先达到者生效）；主题文件不预加载，由 Claude 在需要时通过 Read 工具按需读取。失效方式有三种——人工编辑删除、模型主动整理归档、或设置 autoMemoryEnabled: false 整体关闭。Auto Memory 默认开启，也可用 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 环境变量强制关闭。
三、控制权：合规边界与可追溯性
CLAUDE.md 之所以放在 git 仓库里，是为了让它对团队所有人生效。但项目级 CLAUDE.md 不能改写某些高危配置（例如 Auto Memory 的存储目录）——这是 Anthropic 明确划定的「信任边界」，防止恶意仓库通过配置文件操纵本地数据。
Auto Memory 的控制权设计更微妙：模型自己决定写什么，但开发者保留最终审计权。/memory 命令会列出当前会话加载的所有 CLAUDE.md 与 Auto Memory 文件，并提供打开编辑器的方式。开发者可以删除、修改任意条目，模型不会拒绝或回滚。
四、持久化方式：从磁盘到云端
| 维度 | CLAUDE.md | Auto Memory |
|---|---|---|
| 存储路径 | 仓库内：./CLAUDE.md、./.claude/CLAUDE.md、./.claude/rules/*.md |
~/.claude/projects/<sanitized-repo>/memory/ |
| 用户/本地级路径 | ~/.claude/CLAUDE.md、./CLAUDE.local.md |
同上，但每个 git 仓库独立目录 |
| 是否进 git | 项目级进、个人级不进 | 全不进，纯本机 |
| 是否跨机器同步 | 项目级天然随 git 同步 | 不同步，机器之间不共享 |
| 是否跨 worktree 共享 | 共享（项目级文件） | 同一 git 仓库的所有 worktree 共享同一目录 |
注意 Auto Memory 的目录派生逻辑：路径基于 git 仓库根目录的哈希值，因此同一仓库的多个 worktree 与子目录共享一份记忆；脱离 git 仓库时回退到项目根目录派生。
五、混合使用：让两类机制各司其职
5.1 落地的三步流程
- 打开
/memory，确认当前会话加载的 CLAUDE.md 与 Auto Memory 文件清单； - 区分两类内容：显式规则、必须遵守的约束写入 CLAUDE.md；调试心得、用户偏好、工具习惯交给 Auto Memory；
- 周期性审计：让
/memory把 Auto Memory 的索引与主题文件打开，人工删除过时或敏感条目。
5.2 一个常见的反模式
很多团队把「该项目使用 pnpm 而非 npm」写在 Auto Memory 里，这是不合适的——这是显式契约，应当在 CLAUDE.md 中明文规定、随 git 共享。Auto Memory 适合「用户在某次会话里纠正过一次后被记住」这类隐式偏好。
5.3 配置 Auto Memory 开关
如果某些项目你不希望模型自动写记忆，可以在 .claude/settings.json 里关掉：
{
"autoMemoryEnabled": false
}也可以在项目根目录用 CLAUDE.md 配合 .claude/rules/ 把硬规则与可学习经验分文件托管，团队成员各自维护自己的 CLAUDE.local.md，通过 .gitignore 避免误提交。
六、故障排查：哪些坑最容易踩
CLAUDE.md 写了却没生效？大概率是文件放错了位置或被 claudeMdExcludes 排除；用 /memory 检查加载清单是更直接的诊断方式。Auto Memory 越写越多导致索引膨胀？观察 MEMORY.md 是否被附加了 WARNING 提示；超过 200 行或 25KB 后只会加载截断版本，应主动把细节迁移到独立主题文件并精简索引。
到这里，CLAUDE.md 与 Auto Memory 的边界就清楚了：前者是契约，后者是经验；前者由人写、由人改，后者由模型写、由人审；两者共同支撑 Claude Code 的跨会话协作。
常见问题（FAQ）
Q1：可以把 Auto Memory 的内容迁移到 CLAUDE.md 吗？
可以，让 Claude 把某条记忆「写入 CLAUDE.md」即可，之后该信息由人维护。
Q2：CLAUDE.md 越长越好吗？
不是，官方建议单文件 200 行以内，更长会降低遵守度，建议拆分到 .claude/rules/。
Q3：Auto Memory 适合放敏感信息吗？
不适合，它是纯本机明文存储，且不会自动加密，应只放非敏感的调试与偏好。
