刚开始使用Claude Code时，每次用 Claude Code，我都会花一两分钟告诉它这个项目用的是 pnpm，别去碰 npm。告诉它我们的日志要用 logger.info() 不要用 console.log。告诉它提交代码的时候不用加 Co-Authored-By。
这些话，我说了不下百遍。我用了很久才意识到自己一直在这样做。
不是 Claude 记性差。是我没有利用好它的记忆机制。在意识到这件事之前，我一直没有研究过Claude Code的记忆机制。
前面几篇讲了 Plan Mode、Task 系统、Skill 系统——这些工具都在一次会话里发挥作用。但有一个问题它们都没解决：下次打开新会话，这些上下文都不在了。Memory 系统就是用来解决这个问题的。
Claude Code 有一套内置的 Memory 系统，专门用来解决这个问题。但很多人用错了方向——要么根本不知道它的存在，要么知道了之后把什么东西都往里面塞。
这篇文章，我想讲清楚一件事：Memory 不是"让 AI 记住一切"，而是"把反复有效的指令提取出来，让 AI 每次都自动执行"。
理解这个边界，是用好 Memory 系统的关键。
Memory 的底层逻辑：两套互补机制
在讲"该存什么不该存什么"之前，先把底层逻辑讲清楚。
Claude Code 的 Memory 系统，官方文档明确定义为两套互补机制：
- CLAUDE.md files：
你写给 Claude 的持久指令 - Auto memory：
Claude 自己写给自己的学习笔记
两套机制都在每次会话开始时加载。Claude 把它们当作上下文来读，而不是强制执行的配置——这意味着指令越具体、越简洁，遵守的一致性越高。
CLAUDE.md 适合存放你想在每次会话里都生效的规则：构建命令、代码规范、项目架构、"永远做 X"类的约束。
Auto memory 适合让 Claude 自动积累它从你的纠正和偏好里学到的东西：调试模式、API 约定、你的工作习惯。你不需要手动写，Claude 会自己判断什么值得记下来。
这两点值得记住：
推论一：CLAUDE.md 是你写的指令，Auto memory 是 Claude 自己积累的学习。 两者分工不同，不要混淆。
推论二：Memory 是上下文，不是强制配置。 规则越具体，遵守越一致；规则越模糊，越容易被忽略。
关于优先级：CLAUDE.md 和 Auto memory 不是传统意义上的"配置优先级"关系。它们都会被放进 Claude 的上下文里，Claude 会综合判断。
但从使用策略上，应该把 CLAUDE.md 视为"显式规则层"，把 Auto memory 视为"经验补充层"。团队规范、硬性约束、明确偏好，应该写进 CLAUDE.md 或 .claude/rules/；Auto memory 适合让 Claude 自动沉淀调试经验、构建命令、个人习惯和项目模式。
如果两者冲突，不要指望某一方自动覆盖另一方，而应该手动清理冲突：用 /memory 检查 Auto memory，把确定要长期执行的规则提升到 CLAUDE.md，把过期或错误的自动记忆删掉。
四种 CLAUDE.md：放在哪里，给谁看
CLAUDE.md 文件有四个存放位置，形成一个层级结构：
/Library/Application Support/ClaudeCode/CLAUDE.md | |||
./CLAUDE.md./.claude/CLAUDE.md | |||
~/.claude/CLAUDE.md | |||
./CLAUDE.local.md |
加载顺序：从企业策略到个人，层层叠加。更具体的规则可以覆盖更通用的规则。启动时，Claude Code 还会从当前目录向上递归查找 CLAUDE.md 文件，所以在大型仓库里，你可以在不同子目录放置不同的 Memory。
关于 CLAUDE.local.md：这个文件依然有效，官方推荐加入 .gitignore 来存放个人的项目级偏好（比如你的沙盒 URL、测试数据偏好）。如果你在同一个仓库的多个 worktree 之间工作，CLAUDE.local.md 只存在于创建它的那个 worktree——这时可以用 @import 语法引用 home 目录下的文件来跨 worktree 共享个人指令：
# Individual Preferences
- @~/.claude/my-project-instructions.md
最直观的理解：
- 用户 Memory
（ ~/.claude/CLAUDE.md）：关于"我"的偏好，所有项目都适用 - 项目 Memory
（ ./CLAUDE.md）：关于"这个项目"的规则，团队共享
日常用得最多的是这两个。
进阶：用 .claude/rules/ 组织规则
对于大型项目，官方推荐用 .claude/rules/ 目录来模块化管理规则：
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目指令
│ └── rules/
│ ├── code-style.md # 代码风格规范
│ ├── testing.md # 测试约定
│ └── security.md # 安全要求
rules/ 里的文件有一个特别有用的功能：路径前置条件。通过 YAML frontmatter 的 paths 字段，可以让某条规则只在 Claude 处理特定文件时才加载：
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
这样，API 规则只在 Claude 读取 src/api/ 下的文件时才进入上下文，不会在处理其他文件时占用 token。
用户级别的规则也支持：在 ~/.claude/rules/ 下放置的文件，对你机器上的所有项目都生效。
Auto Memory：让 Claude 自己记笔记
这是很多人不知道的功能，也是官方文档里专门介绍的第二套机制。
Auto memory 默认开启。 Claude 会在工作过程中自动保存它认为值得记住的内容——构建命令、调试模式、架构笔记、你的代码风格偏好。它不是每次会话都写，而是自己判断什么信息在未来的对话里有用。
存储位置在 ~/.claude/projects/<project>/memory/，结构如下：
~/.claude/projects/<project>/memory/
├── MEMORY.md # 简洁索引，每次会话都加载（前200行或25KB）
├── debugging.md # 调试模式详细笔记
├── api-conventions.md # API 设计决策
└── ... # Claude 自己创建的其他主题文件
MEMORY.md 是索引文件，每次会话开始时自动加载（前 200 行或 25KB）。详细内容放在各主题文件里，Claude 按需读取。
如何触发 Auto memory：当你在对话里说"记住用 pnpm，不要用 npm"或者"记住 API 测试需要本地 Redis"，Claude 会把这些保存到 Auto memory。如果你想明确写入 CLAUDE.md，需要说"把这条加到 CLAUDE.md"，或者通过 /memory 命令手动编辑。
开关 Auto memory：在会话里输入 /memory，可以看到 auto memory 的开关，也可以在项目设置里配置：
{
"autoMemoryEnabled":false
}
或者通过环境变量：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
怎么添加 Memory：两种方法
方法一：直接告诉 Claude（最自然）
在对话里直接说你想记住的内容：
记住这个项目用 pnpm，不要用 npm 或 yarn
Claude 会把这条保存到 Auto memory。如果你想明确写入 CLAUDE.md，说"把这条加到 CLAUDE.md"。
方法二：/memory 命令（精细编辑）
在对话中输入 /memory，系统会列出当前会话加载的所有 CLAUDE.md、CLAUDE.local.md 和 rules 文件，以及 Auto memory ,Auto-dream的开关和文件夹入口。选择任意文件可以直接在编辑器里修改。
适合批量整理、重新组织 Memory 内容，或者删除过期的规则。
什么该存：三类黄金候选
类型一：反复出现的纠正
如果你发现自己在不同对话里告诉 Claude Code 同样一件事，这条规则就应该进 Memory。
常见的例子：
## 工具偏好
- 使用 pnpm，不要使用 npm 或 yarn
- 使用 vitest 做测试，不要使用 jest
- 日志使用 logger.info() / logger.error()，不要用 console.log
## Git 规范
- 提交信息用中文
- 不要在提交信息里加 Co-Authored-By
- 所有提交需要通过 lint 检查
这类 Memory 直接节省你的时间，让 Claude Code 一上来就按照你的工作习惯行事。
类型二：项目背景和约束
新对话开始时，Claude Code 对这个项目一无所知。把关键背景提前写进 Memory，避免每次都解释一遍：
## 项目背景
这是一个 Next.js 14 + PostgreSQL 的 SaaS 项目，使用 app router。
主要技术栈：
- 前端：Next.js 14, Tailwind CSS, Shadcn UI
- 后端：Prisma ORM, Zod 验证
- 测试：vitest + Playwright
- 部署：Vercel
## 代码规范
- TypeScript strict mode，所有函数需要明确类型
- 组件文件用 PascalCase，工具函数用 camelCase
- 数据库操作统一走 src/lib/db.ts，不要直接导入 prisma client
类型三：个人工作习惯
用户级别的 Memory 适合存放跨项目的个人偏好：
## 我的工作风格
- 解释代码时先讲结论，再讲细节
- 遇到多种方案时，给出 2-3 个选项并说明权衡，不要直接替我决定
- 代码审查时，请指出潜在的性能问题和安全风险
- 不要主动帮我更新文档，除非我明确要求
什么不该存：三类常见误区
误区一：实现细节
这是最常见的错误。把代码实现放进 Memory：
# 不好的 Memory
用户认证逻辑在 src/auth/middleware.ts，具体实现如下：
```typescript
export const authMiddleware = async (req, res, next) => {
const token = req.headers.authorization?.split(' ')[1]
if (!token) return res.status(401).json({ error: 'Unauthorized' })
// ... 100 行代码
}
这类内容**应该在代码里**，不应该在 Memory 里。Claude Code 可以直接读取代码文件，Memory 里放代码只会制造冗余和潜在的不一致。
当代码更新了，Memory 还没更新，这条记忆就成了错误信息。
### 误区二：会变化的事实
版本号、URL、API key、临时约定——这些会变的东西不适合放进 Memory：
```markdown
# 不好的 Memory
当前使用的 OpenAI 模型是 gpt-4-0125-preview。
数据库连接地址是 postgresql://user:/db。
版本号会升级，地址会变更，密钥会轮换。过期的 Memory 比没有 Memory 更危险——它会主动误导 Claude Code。
这类信息应该在 .env 文件里，或者在代码注释里标注"请查看最新配置"。
误区三：应该在 Git 里的决策
架构决策、技术选型的原因、某次重构的背景——这些内容应该在 Git commit message、ADR（架构决策记录）或项目文档里，不应该在 Memory 里：
# 不好的 Memory
我们从 class components 迁移到了 hooks，
主要原因是团队更熟悉函数式写法，
迁移是在 2024 年 Q3 完成的，
迁移过程中发现了几个性能问题……
Memory 是"给 AI 的指令"，不是"给未来的自己的备忘录"。项目历史应该在 Git 里留存，而不是在 Memory 文件里堆积。
写好 Memory 的三个原则
原则一：具体，不要抽象
# 不好
遵循最佳实践编写代码。
# 好
函数长度控制在 50 行以内，超过时拆分为更小的函数。
"最佳实践"对 Claude Code 是无意义的输入。"50 行以内"是可以执行的标准。
原则二：同时说"做什么"和"不做什么"
只说"做什么"往往不够，好的 Memory 把边界也说清楚：
## 错误处理
使用项目统一的 AppError 类处理业务错误（在 src/errors/index.ts 中定义）。
**不要**：
- 不要直接 throw new Error()（无法被统一捕获）
- 不要在控制器里 try-catch 后沉默吞掉错误
- 不要用 console.error 代替日志系统
这类 Memory 学习自真实的返工经历——某次 Claude Code 的处理方式不对，你纠正了它，然后把这条规则写进 Memory，下次就不会再犯。
原则三：带上"为什么"
Claude Code 理解了原因，会做出更好的举一反三：
# 只有规则
使用 Map 而不是对象来存储动态键值对。
# 规则 + 原因（更好）
使用 Map 而不是对象来存储动态键值对。
**原因**：对象的键会被 JavaScript 引擎优化为固定结构，
频繁增删键会导致性能下降（V8 的 hidden class 机制）。
Memory 的维护：别让它腐烂
Memory 有一个容易忽视的特性：它不会自动更新。
你在第一个月写下的规则，半年后可能已经不适用了：
依赖升级了，某个 workaround 不再需要 架构调整了，某些文件路径变了 团队规范更新了，但 Memory 没跟上
过期的 Memory 不是"没用"，而是"有害"——它会引导 Claude Code 按照过时的规则行事。
官方文档也明确指出：如果两条规则互相矛盾，Claude 可能会随机选一条执行。所以定期清理冲突规则，和定期清理过期规则一样重要。
建议的维护节奏：
- 每次架构变更时：
检查 Memory 里是否有受影响的规则 - 每次发现 Claude Code 行为异常时：
排查是否是 Memory 里有冲突或过期的规则（见下文排错） - 每季度：
用 /memory命令过一遍 Memory 文件，删除或更新过时的条目
维护 Memory 的目标很简单：每一条 Memory 都应该是当下依然有效的指令。
一个有 10 条精准规则的 Memory，远比一个有 100 条规则（其中一半过期）的 Memory 有用。
排错：Claude 不遵守 Memory 怎么办
这是官方文档专门列出的常见问题，值得单独说一下。
CLAUDE.md 内容是作为用户消息注入上下文的，不是系统提示的一部分。 Claude 会读取并尽量遵守，但没有强制保证——尤其是规则模糊或存在冲突时。
遇到 Claude 没有按 Memory 行事，按这个顺序排查：
- 运行
/memory，确认你的 CLAUDE.md 和 CLAUDE.local.md 文件确实被加载了。如果文件没有出现在列表里，Claude 根本看不到它。 - 检查文件位置，确认相关 CLAUDE.md 在当前会话能加载到的路径下。
- 让规则更具体。"用 2 空格缩进"比"格式化代码"有效得多。
- 检查冲突规则。如果多个 CLAUDE.md 文件对同一行为给出了不同指令，Claude 可能会随机选一条。
- Auto memory 里有没有相反的记录？运行
/memory打开 auto memory 文件夹，看看 Claude 自己记了什么。
如果你想让某条指令在系统提示层面生效（更强的保证），可以用 --append-system-prompt 参数——但这需要每次启动时手动传入，更适合脚本和自动化场景，不适合日常交互。
Memory 与其他工具的分工
理清楚 Memory 和其他持久化机制的边界，能帮你做出更好的判断：
一个判断方法：如果这条信息对"下一个开始新对话的人"有用，那它可能适合放进 Memory。如果它只对当前这个任务有用，就不适合。
比如：
"用 pnpm"——对每次新对话都有用，放 Memory。 "这次功能里，先实现登录，再实现注册"——只对当前任务有用，放 Plan 或 Task。 "src/auth/middleware.ts 里有个 token 验证函数"——代码事实，Claude Code 可以直接读代码，不需要放 Memory。
如果你想要更完整的 CLAUDE.md 模板（开发项目和内容创作项目），可以看我前面那篇独立文章：《给 Claude 写一份"入职手册"：CLAUDE.md 完全指南》。
小结
Memory 系统的核心：两套互补机制，都在每次会话开始时加载。
CLAUDE.md：你写的指令。四种位置按需选择——企业级、项目级（团队共享进 Git）、用户级（个人跨项目）、本地项目级（个人不进 Git）。大型项目可以用 .claude/rules/ 模块化管理，支持路径前置条件。
Auto memory：Claude 自己写的学习笔记。默认开启，存在 ~/.claude/projects/<project>/memory/，通过 /memory 命令管理。
该存的：反复纠正、项目约束、个人偏好。
不该存的：实现细节、会变化的事实、应该在 Git 里的决策。
定期维护，删除过期规则，清理冲突指令，保持精准。
遇到 Claude 不遵守 Memory，先用 /memory 确认文件是否被加载，再检查规则是否足够具体、是否存在冲突。
一个好的 Memory 系统不是越全越好，而是越准越好。每条规则都在实际发挥作用，才值得留下来。
另外补一句：本篇讲的是 Claude Code 的原生 Memory 层（CLAUDE.md + Auto memory），适合大多数场景。
