Claude Code 的记忆机制：从 CLAUDE.md 到 Auto Memory，它到底记住了什么？

Claude Code 刚上线了一个新功能叫 Auto Memory - 让 AI 自己记笔记，下次对话自动带上。

听起来很美好，但如果你不理解它的记忆体系是怎么分层的，很容易搞出一堆互相矛盾的指令，或者发现"明明告诉过它"的东西下次又忘了。

这篇把 Claude Code 的记忆机制从头理清。

一、两种记忆

Claude Code 的记忆分两大类：

• CLAUDE.md - 你写给它的指令。类似于项目的 .editorconfig 或 .eslintrc，只不过是用自然语言写的
• Auto Memory - 它自己写给自己的笔记。工作过程中发现的模式、踩过的坑、你的偏好，它会主动记下来

一个是你告诉它该怎么做，一个是它自己总结经验。

二、六层记忆结构

CLAUDE.md 不是一个文件，而是一个层级体系。从全局到局部，Claude Code 会依次加载：

层级	位置	谁维护	共享范围
组织策略	/Library/Application Support/ClaudeCode/CLAUDE.md	IT/DevOps	组织内所有人
项目记忆	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队	通过 Git 共享
项目规则	./.claude/rules/*.md	团队	通过 Git 共享
用户记忆	~/.claude/CLAUDE.md	个人	所有项目
项目本地	./CLAUDE.local.md	个人	仅当前项目
Auto Memory	~/.claude/projects/<project>/memory/	Claude 自己	仅你自己

越具体的层级优先级越高。项目规则覆盖用户偏好，本地配置覆盖项目配置。

这个设计很像 Git 的配置层级 - --system、--global、--local。

三、CLAUDE.md 怎么写

CLAUDE.md 本质上就是 Markdown 文件，用自然语言写指令。比如：

# 项目约定

- 使用 pnpm，不要用 npm
- 测试命令：pnpm test
- 提交前必须跑 lint

# 代码风格

- TypeScript 严格模式
- 组件用 PascalCase，工具函数用 camelCase
- 不要自动加注释和 docstring

几个实用建议：

把常用命令写进去。Claude Code 每次都要去翻 package.json 找构建命令，不如直接告诉它。

写具体的约定，不写模糊的要求。"代码要简洁" 没什么用，"函数不超过 30 行" 才有约束力。

用 /init 自动生成。Claude Code 会扫描项目结构，生成一份基础的 CLAUDE.md。不完美，但比从零开始快。

四、模块化规则

当项目变大，一个 CLAUDE.md 会变得又长又杂。.claude/rules/ 目录解决这个问题 - 按主题拆分成独立文件：

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── testing.md

更有意思的是条件规则 - 只在处理特定文件时生效：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有端点必须做输入校验
- 使用标准错误响应格式

所有 rules 文件在启动时都会被读取（包括 paths 元数据），但带 paths 的规则只在 Claude 实际读写匹配文件时才生效 - 也就是说，这条规则在你处理前端代码时不会影响 Claude 的行为，只有碰到 src/api/ 下的 TypeScript 文件时才会起作用。

五、Auto Memory 是什么

这是新功能。以前所有记忆都要你手动维护，现在 Claude Code 会在工作过程中自己记笔记。

它记什么？

• 项目模式：构建命令、测试约定、代码风格
• 调试经验：遇到过的坑、解决方案
• 架构笔记：关键文件、模块关系
• 你的偏好：沟通风格、工作习惯、工具选择

存在 ~/.claude/projects/<project>/memory/ 下，每个项目独立。目录结构是：

memory/
├── MEMORY.md          # 索引文件，每次启动加载前 200 行
├── debugging.md       # 调试相关笔记
├── api-conventions.md # API 设计决策
└── ...

MEMORY.md 是入口。Claude Code 启动时只加载这个文件的前 200 行，所以它需要保持精简。详细内容放在独立的主题文件里，Claude 需要时再读取。

六、Auto Memory 的边界

Auto Memory 默认开启。如果不想用：

• 对话里跑 /memory，有个开关可以关
• 在 ~/.claude/settings.json 里加 "autoMemoryEnabled": false
• 环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 强制关闭（适合 CI）

你也可以主动让它记住东西：

"记住我们用 pnpm 不用 npm" "保存到记忆：API 测试需要本地 Redis"

反过来也行：

"忘掉之前关于 Redis 的记忆"

记忆文件就是普通 Markdown，随时可以手动编辑。跑 /memory 会打开你的编辑器。

七、导入机制

CLAUDE.md 支持 @path/to/file 语法导入其他文件：

参考 @README 了解项目概况，@package.json 查看可用命令。

# 额外指令
- Git 工作流 @docs/git-instructions.md

相对路径基于当前文件所在目录解析，不是工作目录。支持递归导入，最深 5 层。

一个实用场景：如果你用 Git worktree，CLAUDE.local.md 只存在于一个 worktree 里。把个人配置放到 home 目录，然后导入：

# 个人偏好
- @~/.claude/my-project-instructions.md

这样所有 worktree 共享同一份个人指令。

八、加载时机

理解加载时机很重要，否则你会纳闷"为什么没生效"：

• 启动时全量加载：工作目录往上的所有 CLAUDE.md、CLAUDE.local.md、~/.claude/rules/*.md、Auto Memory 的 MEMORY.md 前 200 行
• 按需加载：子目录下的 CLAUDE.md 只在 Claude 读取那个目录的文件时才加载；Auto Memory 的主题文件在需要时读取
• 条件加载：.claude/rules/ 里有 paths 字段的规则只在匹配文件时生效

这意味着你可以在 monorepo 的每个子包里放自己的 CLAUDE.md，不会一开始就把所有指令都塞进上下文。

怎么用才合理

几条建议：

1. 项目 CLAUDE.md 写团队共识，提交到 Git。构建命令、代码规范、架构决策。
2. CLAUDE.local.md 写个人偏好，它自动加到 .gitignore。你的测试数据路径、沙箱 URL。
3. Auto Memory 让它自己跑，定期检查一下 MEMORY.md 有没有记错的。
4. 不要重复。如果 CLAUDE.md 里已经写了 "用 pnpm"，Auto Memory 再记一遍就是噪音。
5. 保持精简。MEMORY.md 超过 200 行就会被截断。把细节移到独立文件。

记忆越多不代表越好。Claude Code 每次启动都会把这些内容塞进 system prompt，占的是你的上下文窗口。写得精准、组织得清楚，比写得多更重要。