彻底搞懂 Claude Code 的“记忆”机制：让 AI 拥有跨会话的“肌肉记忆”
每个 Claude Code 会话都从一张白纸开始，如何让它记住你的项目规范、调试经验和个人偏好？本文带你全面梳理 Claude Code 的记忆系统，从此告别每次都要重复说明的痛苦。
🧠 核心概念：Claude 的“记忆”到底是什么？
很多新手会误以为 Claude Code 像人一样有长期的“潜意识”，但实际上，Claude Code 每次启动都是一个全新的上下文窗口，它不会自动记住上次聊了什么。
所谓的“记忆”，本质上是：每次启动时，从磁盘读取一堆 Markdown 文件 → 注入到 Prompt → 当作上下文参考。
目前，跨会话传递知识主要依赖两套系统：
- CLAUDE.md 文件：你手写给 AI 的规则。
- 自动记忆（Auto Memory）：AI 自己记的笔记。
用一张图概括整个记忆系统的全貌：
⚠️ 重要提醒：这两个系统都是“参考上下文”，不是“强制配置”。Claude 会尽量遵守，但不保证 100% 绝对执行。
📝 一、CLAUDE.md：你写给 AI 的“长期指令”
这是你最核心的工具，用来告诉 Claude “你在这个项目里必须遵守的规矩”。
1. 什么时候该往里写东西？
- Claude 第二次犯同样的错误时；
- Code Review 发现它不懂的项目约定时；
- 你在每个会话都要重复同一套纠正/说明时；
- 新队友需要同样的上下文才能高效工作时。
原则：把“每次会话都应该知道的事实”写进去。（比如：构建命令、代码规范、项目架构、绝对不要做的事）
2. CLAUDE.md 的层级与作用域
Claude Code 会从当前目录往上遍历，串联所有找到的 CLAUDE.md，而不是覆盖。上层目录的先出现，靠近项目根目录的后出现（优先级更高）。
| 范围 | 文件位置（示例） | 适用场景 | 共享对象 |
|---|---|---|---|
| 组织级指令 | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) 等 |
全公司统一安全/合规规范 | 全组织 |
| 用户级指令 | ~/.claude/CLAUDE.md |
你的个人偏好（如：喜欢中文回复） | 只自己 |
| 项目级指令 | ./CLAUDE.md 或 ./.claude/CLAUDE.md |
团队项目规范（需提交到 Git） | 团队 |
| 本地指令 | ./CLAUDE.local.md（需加入 .gitignore） |
你在本项目里的个人偏好/试错 | 只自己 |
| 💡 技巧：子目录里的 CLAUDE.md 不是启动就加载，而是 Claude 读取该子目录文件时才按需加载，这能节省 Token。 |
3. 编写最佳实践
- 大小：每个文件目标 ≤ 200 行。太长会多吃 Token，且 AI 遵守度会下降。
- 结构：用 Markdown 标题 + 列表，方便 AI 扫描。
- 具体性：写可验证的指令。例如 ✅ “使用 2 空格缩进”，而不是 ❌ “正确格式化代码”。
- 导入其他文件：可以用
@path/to/import语法导入 README 等外部文件（最多 4 跳递归），首次使用会弹窗让你确认安全。
🗂️ 二、.claude/rules/：模块化的“规则库”
对于大型项目，把所有规则塞进一个 CLAUDE.md 会变得臃肿。官方推荐使用 .claude/rules/ 目录进行拆分。
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目指令
│ └── rules/
│ ├── code-style.md # 代码样式
│ ├── testing.md # 测试约定
│ └── security.md # 安全要求
杀手锏功能：路径限定
规则文件可以加 YAML frontmatter，限定只在处理某些文件时才触发规则，极大减少无关 Token 消耗：
---
paths:- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
🤖 三、自动记忆：AI 自己记的“小本本”
如果说 CLAUDE.md 是你给 AI 下发的员工手册，那自动记忆就是 AI 自己在工作中攒下来的经验笔记。
1. 工作机制
- 当你纠正它时，它觉得有用的经验会自动保存下来。
- 存储在本地
~/.claude/projects/<project>/memory/目录下。 MEMORY.md的前 200 行或 25KB 会在每次会话开始时自动加载，超出的部分会按主题拆分（如debugging.md），在需要时按需读取。
2. 管理与控制
- 默认开启，如果你不想让它自作主张记东西，可以通过
/memory界面关闭开关，或在设置中配置"autoMemoryEnabled": false。 - 自动记忆是机器本地的，不会同步到云端，也不会提交到 Git。
🎛️ 四、/memory 命令：一站式控制台
在会话中输入 /memory，是你管理和调试记忆系统的最佳入口：
- 📋 查看：列出当前会话加载的所有 CLAUDE.md 和规则文件。
- ✏️ 编辑：直接打开任何记忆文件进行修改。
- 🔌 开关：一键开启/关闭自动记忆功能。
💡 当你跟 Claude 说“记住要用 pnpm”，它会存到自动记忆；如果你希望写进团队规范，明确说“把它加到 CLAUDE.md”，或者自己通过/memory编辑。
🛠️ 五、常见问题与避坑指南
Q1：为什么 Claude 不遵守我的 CLAUDE.md？
- 用
/memory确认文件是否真的被加载了。 - 检查指令是否太模糊，改用具体可验证的描述。
- 检查不同层级/文件之间是否有冲突规则，AI 遇到冲突会随机选一条。
- 如果是“必须在某时机执行”的命令（如提交前检查），应该用 Hook 而不是 CLAUDE.md。
Q2：CLAUDE.md 太大了怎么办？
- 把只跟特定文件类型相关的规则挪到
.claude/rules/，加paths限定。 - 修剪不是每个会话都需要的内容。
Q3：使用 /compact 压缩上下文后，指令好像丢了？
- 项目根目录的 CLAUDE.md 在压缩后会自动从磁盘重新读取。
- 但子目录中的 CLAUDE.md 需要等 AI 再次读取该子目录文件时才会重新加载。
- 对策：把最核心的指令放在项目根目录的 CLAUDE.md 中。
💬 总结
Claude Code 的记忆系统设计非常优雅：你定基调（CLAUDE.md + Rules），它补细节（Auto Memory），通过 /memory 随时审视。
掌握这套机制，你就能把 Claude Code 从一个“每次都要重新磨合的临时工”，调教成一个“深谙项目套路的资深搭档”。
📖 官方文档参考：https://code.claude.com/docs/zh-CN/memory