Claude Code 的 Memory 系统：让 AI 记住你的偏好

刚开始使用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 文件有四个存放位置，形成一个层级结构：

加载顺序：从企业策略到个人，层层叠加。更具体的规则可以覆盖更通用的规则。启动时，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:pass@staging.example.com/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 可能会随机选一条执行。所以定期清理冲突规则，和定期清理过期规则一样重要。

建议的维护节奏：

1. 每次架构变更时：
   检查 Memory 里是否有受影响的规则
2. 每次发现 Claude Code 行为异常时：
   排查是否是 Memory 里有冲突或过期的规则（见下文排错）
3. 每季度：
   用 /memory 命令过一遍 Memory 文件，删除或更新过时的条目

维护 Memory 的目标很简单：每一条 Memory 都应该是当下依然有效的指令。

一个有 10 条精准规则的 Memory，远比一个有 100 条规则（其中一半过期）的 Memory 有用。

排错：Claude 不遵守 Memory 怎么办

这是官方文档专门列出的常见问题，值得单独说一下。

CLAUDE.md 内容是作为用户消息注入上下文的，不是系统提示的一部分。 Claude 会读取并尽量遵守，但没有强制保证——尤其是规则模糊或存在冲突时。

遇到 Claude 没有按 Memory 行事，按这个顺序排查：

1. 运行 /memory，确认你的 CLAUDE.md 和 CLAUDE.local.md 文件确实被加载了。如果文件没有出现在列表里，Claude 根本看不到它。
2. 检查文件位置，确认相关 CLAUDE.md 在当前会话能加载到的路径下。
3. 让规则更具体。"用 2 空格缩进"比"格式化代码"有效得多。
4. 检查冲突规则。如果多个 CLAUDE.md 文件对同一行为给出了不同指令，Claude 可能会随机选一条。
5. 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），适合大多数场景。如果你需要更高级的动态记忆（自动捕获会话历史、跨会话语义检索），可以再看两篇：

• 《让 Claude 拥有"记忆"：Claude MEM 完全指南》
• 《Claude Code 记忆插件选型指南》