第 3 章：三层记忆体系——把偏好变成项目资产

第 3 章：三层记忆体系——把偏好变成项目资产

上一章解决了「单次对话内 AI 会遗忘」的问题，这一章解决「每次开新会话都要重新告诉 AI 项目规范」的问题。Claude Code 的记忆系统分为两大体系：你手动编写的CLAUDE.md（指令与规则）和 Claude 自动学习的 Auto Memory（经验与发现）。本章将深度拆解记忆体系的结构、每一层的用法、以及记忆管理的核心原则。

3.1 为什么需要跨会话记忆

3.1.1 痛点场景

每次开启一个新的 Claude Code 会话，AI 的上下文都是空白的。如果你不做任何配置，每次都要重复说一遍：

"我的项目用的是 React 18 + TypeScript + Vite" "代码规范用 ESLint + Prettier，缩进 2 空格" "接口请求统一封装在 src/utils/request.ts 里" "组件命名用 PascalCase，函数用 camelCase" "不要用 any，类型要严格定义" "包管理器用 pnpm，不要用 npm 或 yarn"

这些信息在每个会话中都是一样的，但 AI 默认不会跨会话记住。每次重复输入不仅浪费时间，还可能因为某次忘记说而导致 AI 生成不符合规范的代码。

更糟糕的是，有些「隐性知识」你甚至不会每次都想起来说——比如「这个项目的数据库连接池大小设为 20」「部署脚本在 scripts/deploy.sh」「上次调试发现某个第三方库有 bug 需要用特定版本」。这些信息如果不沉淀到记忆中，AI 每次都会「重新踩坑」。

3.1.2 记忆 vs 上下文压缩的本质区别

上一章讲的/compact上下文压缩和本章讲的记忆系统，都涉及「保留信息」，但它们是完全不同的东西：

一句话总结：上下文压缩管「这次对话做了什么」，记忆系统管「这个项目的规矩和经验是什么」。两者配合使用，AI 才能既知道当前进度，又遵守项目规范。

3.2 记忆体系全景

3.2.1 两大体系：CLAUDE.md vs Auto Memory

根据 Anthropic 官方文档，Claude Code 的记忆系统分为两大体系：

核心理解：CLAUDE.md是你给 AI 下的「规矩」，Auto Memory 是 AI 在工作中自己总结的「经验」。规矩是显性的、你主动制定的；经验是隐性的、AI 被动积累的。

3.2.2 CLAUDE.md 的三级作用域

CLAUDE.md本身又分为三个级别，按优先级从高到低：

叠加规则：三级 CLAUDE.md 会合并加载，项目级覆盖用户级，用户级覆盖组织级。你可以在组织级放企业通用规范，在用户级放个人偏好，在项目级放项目特有约定。

注意：组织级 CLAUDE.md 需要企业版 Claude Code 支持，个人用户通常只用到项目级和用户级。

3.2.3 Auto Memory 的存储结构

Auto Memory 是 Claude 在工作过程中自动学习和记录的内容，存储在以下位置：

~/.claude/ ├── MEMORY.md # 用户级自动记忆（跨所有项目） ├── memory/ # 用户级分文件记忆（独立记忆条目） └── projects/ └── {project-hash}/ ├── MEMORY.md # 项目级自动记忆 └── memory/ # 项目级分文件记忆 ├── user-preferences/ ├── debugging-notes/ └── ...

Auto Memory 的特点：

• 自动创建：Claude 在对话中发现重复出现的模式、偏好、经验时，自动写入记忆文件
• 按需检索：启动时只加载前 200 行（约 25KB），其余内容在需要时通过语义检索加载
• 自动整合：Claude 会定期运行「Dreams」机制，合并重复记忆、替换过时的值、提炼新洞察
• 个人专属：Auto Memory 是按用户和项目隔离的，不会跨用户共享

3.2.4 独立记忆文件的结构

除了MEMORY.md汇总文件，Auto Memory 还支持独立的记忆文件，每个文件存储一条记忆，带有 frontmatter 元数据：

--- name: prefer-pnpm-over-npm description: 用户偏好使用 pnpm 而非 npm 或 yarn metadata: type: user --- 用户在所有项目中优先使用 pnpm 作为包管理器。 **Why:** 用户认为 pnpm 速度更快、磁盘占用更少（硬链接共享），且 monorepo 支持更好。 **How to apply:** 安装依赖时使用 `pnpm install`，运行脚本使用 `pnpm run <script>`，不要建议 npm 或 yarn。

frontmatter 字段说明：

• name：记忆的唯一标识（slug 格式）
• description：记忆的简短描述
• metadata.type：记忆类型，可选值见下表

四种记忆类型：

关联记忆：使用[[slug-name]]语法可以关联相关的记忆文件。例如[[prefer-pnpm-over-npm]]会链接到 pnpm 偏好的记忆文件，形成记忆之间的关系网络。

3.3 CLAUDE.md 深度指南

3.3.1 CLAUDE.md 应该包含什么

CLAUDE.md是项目的「宪法」，AI 每次会话启动时第一个读取的文件。它应该包含 AI 需要知道、但无法从代码中自动推断的信息。

推荐结构：

# 项目名称 ## 概述 （2-3 行描述项目是做什么的，技术栈是什么） ## 构建与运行 （常用命令列表，如安装依赖、启动开发、运行测试、构建生产版本） ## 项目结构 （关键目录的用途说明，不需要列出所有文件） ## 编码规范 （代码风格、命名约定、技术选型的硬性要求） ## 重要约定 （AI 必须遵守的特殊规则，如不要修改自动生成的文件、环境变量声明方式等）

3.3.2 完整模板示例

# 用户管理系统（User Management System） ## 概述 企业级用户管理平台，支持 RBAC 权限控制、SSO 单点登录、操作审计日志。 技术栈：React 18 + TypeScript + Vite（前端），Express + PostgreSQL + Sequelize（后端）。 ## 构建与运行 \`\`\`bash pnpm install # 安装依赖（必须用 pnpm，不要用 npm/yarn） pnpm dev # 启动前后端开发服务器（前端 5173，后端 3000） pnpm test # 运行单元测试 pnpm test:e2e # 运行端到端测试 pnpm build # 生产构建 pnpm lint # 代码检查 \`\`\` ## 项目结构 - `frontend/src/` - 前端源码 - `pages/` - 页面组件（按功能模块组织） - `components/` - 公共组件 - `api/` - API 调用层（统一走 client.ts） - `store/` - 状态管理（Zustand） - `backend/src/` - 后端源码 - `routes/` - 路由（按模块组织） - `models/` - Sequelize 模型 - `middleware/` - 中间件 - `services/` - 业务逻辑层 - `docs/` - 项目文档 ## 编码规范 - 严格 TypeScript，**禁止使用 any**，需要时定义明确的接口 - 组件使用函数式组件 + Hooks，不要使用 class 组件 - 状态管理使用 Zustand，不要引入 Redux - API 请求统一走 `frontend/src/api/client.ts`，不要直接调用 axios - 样式使用 Tailwind CSS，不要创建独立的 CSS 文件 - 文件名：组件用 PascalCase（`UserTable.tsx`），工具函数用 camelCase（`dateUtils.ts`） - 提交信息遵循 Conventional Commits：`feat:`, `fix:`, `refactor:`, `docs:`, `chore:` ## 重要约定 - **不要修改** `frontend/src/generated/` 和 `backend/src/generated/` 目录下的文件（自动生成） - 环境变量通过 `.env.example` 声明，实际值放在 `.env`（已加入 .gitignore） - 数据库迁移使用 `pnpm db:migrate`，不要手动修改数据库表结构 - PR 合并前必须通过：`pnpm lint && pnpm test && pnpm build` - 密码加密统一使用 bcrypt（salt rounds = 10），不要使用其他加密方式 - API 返回格式统一为 `{ code: number, data: any, message: string }`

3.3.3 创建方式

方式一：手动创建

直接在项目根目录创建CLAUDE.md文件，按照上面的模板编写。这是最灵活的方式，适合对项目已经很熟悉的情况。

方式二：/init 命令交互式创建

/init

Claude 会自动扫描项目文件，提取以下信息：

• 技术栈（从 package.json、配置文件中识别）
• 常用命令（从 package.json 的 scripts 中提取）
• 项目结构（扫描目录树）
• 现有规范（从 ESLint、Prettier 配置中提取）

然后生成一份CLAUDE.md草稿，你可以确认、补充和修改。这比从零手写高效得多，推荐新项目使用。

3.3.4 最佳实践

✅ 应该做的：

1. 保持简短：建议不超过 200 行（约 2K Token 以内）。CLAUDE.md 每次会话全量加载，越长越浪费上下文空间。
2. 写「约定」而非「文档」：告诉 AI怎么做（规则、约束、命令），而不是是什么（项目背景介绍、详细的功能说明）。后者放在docs/目录中，需要时 AI 可以按需读取。
3. 定期更新：项目演进后（技术栈变更、新增规范、目录结构调整），及时同步更新 CLAUDE.md。过时的规范比没有规范更危险——AI 会按照旧规范生成错误的代码。
4. 信息密度高：每一行都应该是 AI 需要知道的规则，不要写废话。用列表和代码块，少用大段文字。
5. 明确禁止事项：把「不要做什么」写清楚，如「不要修改自动生成的文件」「不要使用 any」「不要用 npm」。禁止事项比允许事项更重要。

❌ 不应该做的：

1. 不要把整个 README 复制进去：README 是给人看的项目介绍，包含大量背景信息，AI 不需要这些。
2. 不要写 Claude 可以从代码中自动推断的信息：比如「项目使用 React」——AI 看 package.json 就知道了，不需要在 CLAUDE.md 里重复。但「必须使用函数式组件，不要用 class 组件」这种约束是代码里看不出来的，需要写。
3. 不要写临时信息：「当前正在开发登录功能」这种临时状态不应该写在 CLAUDE.md 里，它属于上下文压缩的范畴。CLAUDE.md 只写长期不变的规范。
4. 不要过于冗长地解释为什么：简单说明规则即可，不需要长篇大论解释背后的原因。比如「用 pnpm，不要用 npm」就够了，不需要解释 pnpm 的原理。

3.4 Auto Memory 与独立记忆文件

3.4.1 Auto Memory 是怎么工作的

Auto Memory 是 Claude 的「自动学习」机制。在对话过程中，Claude 会识别以下模式并自动写入记忆：

• 重复出现的命令：如果你多次运行pnpm test，Claude 会记住「这个项目的测试命令是 pnpm test」
• 用户的纠正和反馈：如果你说「不要用 any，用明确的类型」，Claude 会记住这个偏好
• 调试经验：如果某个 bug 反复出现，Claude 会记录解决方案
• 项目的特殊模式：如「这个项目的 API 总是返回 { code, data, message } 格式」

这些记忆会自动写入MEMORY.md或独立的记忆文件，在后续会话中自动加载或按需检索。

3.4.2 如何主动让 Claude 记住某事

虽然 Auto Memory 是自动的，但你也可以主动告诉 Claude 记住某事：

"记住：这个项目的数据库连接池大小设为 20，不要改。" "记住：我偏好使用 Tab 缩进，宽度为 4。" "记住：部署脚本在 scripts/deploy.sh，每次发版前先运行它。"

Claude 会创建或更新对应的记忆文件。你也可以查看当前的记忆：

"列出你关于这个项目的所有记忆。" "你记住了我哪些偏好？"

3.4.3 记忆的自动整合（Dreams）

Claude Code 会定期运行「Dreams」机制（类似人类睡眠时的记忆整合），对记忆进行：

• 合并重复：如果多条记忆表达相同内容，合并为一条
• 替换过时值：如果新记忆覆盖了旧记忆，更新为最新值
• 提炼新洞察：从多条记忆中提炼出更高层次的模式

这个过程是自动的，不需要手动干预。它确保记忆库不会因为长期积累而变得冗余和矛盾。

3.4.4 独立记忆文件 vs MEMORY.md 汇总

对于重要的、长期有效的记忆（如「用户偏好 pnpm」），Claude 会自动创建独立记忆文件；对于零散的经验记录，会写入 MEMORY.md。

3.5 记忆管理四原则

原则一：不存代码能推导的信息

项目结构、Git 历史、代码内容、依赖版本——这些信息 Claude 可以直接从文件系统中读取，不需要存入记忆。记忆中只存「代码里看不出来的规则和经验」。

❌ 不应该存："项目使用 React 18"（package.json 里有） ✅ 应该存："必须使用函数式组件 + Hooks，不要用 class 组件"（代码里看不出来） ❌ 不应该存："测试命令是 pnpm test"（package.json scripts 里有） ✅ 应该存："PR 合并前必须运行 pnpm lint && pnpm test && pnpm build"（这是流程约定）

原则二：不存仅限本次对话的临时信息

「当前正在开发登录功能」「刚才修复了一个 500 错误」——这些是临时状态，属于上下文压缩的范畴，不应该存入持久化记忆。记忆只存「长期不变或长期有效的信息」。

❌ 不应该存："当前进度：正在做权限管理"（下个会话可能就变了） ✅ 应该存："权限管理使用 RBAC 模型，表结构在 docs/schema.md 中"（长期有效的架构决策）

原则三：及时更新

偏好改变、技术栈迁移、规范调整时，及时更新记忆。过时的记忆比没有记忆更危险——Claude 会按照旧规范生成错误的代码，而你可能不会意识到是记忆过时了。

更新方式：直接告诉 Claude「更新记忆：我们已经从 JavaScript 迁移到 TypeScript 了」，Claude 会自动更新对应的记忆文件。

原则四：定期审查

每隔一段时间（如每月或每个大版本发布后），审查一次记忆内容：

• 移除过时的记忆
• 合并重复的记忆
• 补充遗漏的重要规范
• 确认记忆与当前项目状态一致

可以让 Claude 帮你审查：

"请审查你关于这个项目的所有记忆，指出哪些可能已经过时或不再适用。"

3.6 实战示例：一个配置良好的记忆体系

假设你在一个中型团队项目中工作，配置良好的记忆体系应该是这样的：

项目级 CLAUDE.md（约 80 行，纳入 Git）

# 订单管理系统 ## 概述 电商订单管理平台，支持订单创建、支付、发货、退款全流程。 技术栈：Next.js 14 + TypeScript + Prisma + PostgreSQL。 ## 常用命令 pnpm dev # 启动开发服务器（端口 3000） pnpm test # 运行测试 pnpm build # 生产构建 pnpm db:migrate # 数据库迁移 pnpm db:seed # 填充测试数据 ## 编码规范 - 严格 TypeScript，禁止 any - 使用 App Router（Pages Router 已废弃） - 数据获取使用 React Server Components，客户端交互用 'use client' - ORM 使用 Prisma，不要写原生 SQL - 样式使用 Tailwind + shadcn/ui ## 重要约定 - 不要修改 prisma/generated/（自动生成） - 环境变量通过 .env.example 声明 - 订单状态流转必须经过 OrderService，不要直接修改数据库 - PR 前必须通过 pnpm lint && pnpm test && pnpm build

用户级 CLAUDE.md（约 20 行，个人全局）

# 个人偏好 - 缩进使用 2 空格 - 注释使用中文 - 代码解释不要太啰嗦，直接给关键代码 - 提交信息用英文，遵循 Conventional Commits - 优先使用 pnpm

Auto Memory（Claude 自动学习）

MEMORY.md 中的内容（Claude 自动记录）： - 这个项目的支付回调经常超时，需要检查 webhook 重试机制 - 用户上次调试发现 Stripe SDK v14 有 bug，锁定在 v13.8.1 - 部署脚本在 scripts/deploy.sh，需要先运行 lint 再部署 - 用户偏好先给方案再写代码，不喜欢 AI 直接动手

独立记忆文件（重要的结构化记忆）

~/.claude/memory/prefer-pnpm.md: name: prefer-pnpm type: user 内容：用户在所有项目中使用 pnpm ~/.claude/projects/{hash}/memory/order-status-flow.md: name: order-status-flow type: project 内容：订单状态流转必须经过 OrderService，状态机定义在 src/services/order/status.ts

这样配置后，每次开启新会话，Claude 会：

1. 加载用户级 CLAUDE.md（个人偏好）
2. 加载项目级 CLAUDE.md（项目规范）
3. 加载 Auto Memory 前 200 行（经验教训）
4. 按需检索独立记忆文件（重要规则）

AI 从第一轮对话就知道你的所有规范和偏好，不需要你重复说明。

3.7 本章小结

本章系统讲解了 Claude Code 的三层记忆体系，核心知识点：

1. 两大记忆体系：CLAUDE.md（你手写的指令与规则，全量加载）和 Auto Memory（Claude 自动学习的经验与发现，启动加载前 200 行/25KB，其余按需检索）。前者是「规矩」，后者是「经验」。
2. CLAUDE.md 三级作用域：项目级（<project>/CLAUDE.md，团队共享）> 用户级（~/.claude/CLAUDE.md，个人全局）> 组织级（企业配置）。高优先级覆盖低优先级。
3. CLAUDE.md 最佳实践：保持 ≤200 行（约 2K Token），写「约定」而非「文档」，定期更新，明确禁止事项。用/init命令可交互式创建。
4. Auto Memory 机制：Claude 自动识别重复模式、用户反馈、调试经验并写入记忆，支持独立记忆文件（带 frontmatter：name/description/type），四种记忆类型（user/feedback/project/reference），支持[[slug]]关联，定期通过 Dreams 机制自动整合。
5. 记忆管理四原则：不存代码能推导的信息、不存临时信息、及时更新、定期审查。
6. 记忆 vs 上下文压缩：记忆管「项目规矩和经验」（跨会话持久化），上下文压缩管「当前对话进度」（会话内临时），两者配合使用。

下一章我们将进入代码回退与安全网，学习如何在 AI 改崩代码时快速恢复，以及如何构建多层级的回退机制。

课后思考

1. 基础题：CLAUDE.md和 Auto Memory 有什么本质区别？分别由谁维护、加载方式有什么不同？

   提示：从「谁写的」「内容性质」「加载方式」三个维度对比。

参考答案：

本质区别：
CLAUDE.md是人给AI下达的硬性约束指令，具备强强制性；Auto Memory 是AI自动归纳的历史经验沉淀，不保证每次都能被读到。

2. 基础题：CLAUDE.md 的三级作用域分别是什么？优先级顺序是怎样的？如果你想让团队所有成员都遵循同一个代码规范，应该把配置写在哪一级？

   提示：考虑「团队共享」和「纳入 Git」两个关键词。

参考答案：

1. 三级作用域

• ① 用户全局级：~/.claude/MEMORY.md/ 用户全局配置，作用于本机全部项目，不会提交到Git
• ②项目共享级：项目根目录下CLAUDE.md，作用域为当前整个项目，可以纳入Git版本控制，团队所有人clone项目后自动生效
• ③ 项目本地级：.claude/settings.local.json，仅本机当前项目，.gitignore忽略，不团队共享

2. 优先级顺序：
   项目本地级 > 项目共享级 > 用户全局级，高优先级配置会覆盖低优先级同名配置。

3. 团队统一代码规范放置位置：
   写在项目共享级的根目录CLAUDE.md。
   理由：该文件可以纳入Git版本管理，团队所有成员拉取代码自动获取统一规范；全局级只作用个人，本地级不会提交Git，无法实现团队共享。

3. 进阶题：CLAUDE.md 为什么要保持简短（建议 ≤200 行）？如果项目规范很多，写不下怎么办？

   提示：考虑 CLAUDE.md 每次会话全量加载的特性，以及「详细文档放 docs/ 按需读取」的策略。

参考答案：

为什么需要保持简短（≤200行）

1. CLAUDE.md每一次会话启动都会完整全量加载进入上下文。行数越多，占用token就越大，直接挤占有效对话的上下文空间；
2. 内容冗长会带来注意力稀释，模型难以抓取关键硬性规则，容易忽略重要约束，增大幻觉概率；
3. 文件过长，修改、阅读、团队维护成本都会变高。

规范多写不下的解决方案

1. CLAUDE.md 只保留核心硬性约定：技术栈、关键编码强制规则、启动命令、目录概要、最重要的安全约束；
2. 把详细的长篇规范、架构文档、接口说明，放到项目docs/文件夹，作为独立Markdown文档；
3. 在CLAUDE.md只写索引说明，例如：

完整接口规范参见docs/api-spec.md，复杂架构说明参见docs/architecture.md，需要的时候再读取；

4. AI需要详细文档的时候，按需让AI读取docs下的文件，而不是会话一开始全部加载；
5. 定期清理CLAUDE.md，移除过时、不再生效的旧规则。

4. 进阶题：记忆管理四原则是什么？请判断以下信息应该存入记忆还是只放在当前对话上下文中：(a)「项目使用 PostgreSQL」(b)「密码加密必须用 bcrypt salt rounds=10」©「当前正在开发支付模块」(d)「Stripe SDK v14 有 bug，锁定 v13.8.1」。

   提示：用「代码能推导吗？是临时的吗？」两个问题来判断。

参考答案：

记忆管理四原则

1. 不存储代码可以自动推导的信息：代码、git历史能够读取得到的内容，不要写入记忆；
2. 不存储仅限本次对话的临时信息：只在当前会话有效的临时任务、临时状态，不持久化；
3. 只存储长期稳定的事实、偏好、硬性约束；
4. 定期审查记忆内容，清理过时、失效信息。

案例判断

(a)「项目使用 PostgreSQL」👉存入记忆，属于长期稳定项目事实，代码无法一眼推导，跨会话需要AI知道；
(b)「密码加密必须用 bcrypt salt rounds=10」👉存入记忆，长期硬性编码约束，跨会话必须遵守；
©「当前正在开发支付模块」👉仅当前对话上下文，属于临时任务状态，任务完成之后就失效，不需要跨会话记忆；
(d)「Stripe SDK v14 有 bug，锁定 v13.8.1」👉存入记忆，长期项目约束，跨会话开发都要注意版本锁定，属于稳定的踩坑经验。

小技巧判断口诀：是否长期有效？跨重启会话AI是否需要知道？代码能不能直接读出来？临时状态不要存记忆。

5. 开放题：Auto Memory 是 Claude 自动学习的，你无法完全控制它记住什么、忘记什么。这种「不可控的自动学习」可能带来什么风险？你会如何管理这些风险？

   提示：考虑记忆过时、记忆错误、记忆冲突、隐私泄露等可能性。

参考答案：

潜在风险

1. 记忆过时风险：项目迭代变更，旧的业务规则、技术选型已经修改，但Auto Memory还保留旧的历史记忆，AI继续使用已经废弃的旧规则；
2. 记忆错误（幻觉记忆）：AI错误归纳对话内容，生成不符合项目真实情况的错误记忆，后续开发持续沿用错误信息；
3. 记忆冲突：同时存在多条相互矛盾的记忆，模型不知道采信哪一条，输出行为不稳定；
4. 隐私与敏感信息风险：对话中出现密钥、业务隐私、客户数据，AI可能自动存入Memory，造成敏感信息留存泄露；
5. 关键信息丢失：重要的硬性约束AI没有自动识别并保存，跨会话直接遗忘；不重要的冗余内容反而被大量占用记忆空间。

风险管理手段

1. 关键硬性规则不依赖Auto Memory，写进CLAUDE.md。把必须遵守的强制约定放在每次会话都会加载的CLAUDE.md，作为最高优先级约束，不交给自动记忆；
2. 定期检查Memory内容，手动删除过时、错误、冲突的记忆条目；
3. 对话出现敏感信息之后，明确告诉AI：不要将以上内容保存到记忆，规避隐私泄露；
4. 重要决策完成之后，手动把结论写入项目文档（docs目录），作为可信的信息源，不完全依赖AI记忆；
5. 新开会话时，如果依赖历史经验，可以主动让AI复述相关记忆，校验记忆是否准确；发现记忆错误，立刻明确指令让AI删除错误记忆；
6. 区分信息来源：优先采信项目文档、CLAUDE.md，Auto Memory仅作为辅助经验参考，不作为权威依据。

补充：Auto Memory定位是经验辅助，不能当作权威配置文件使用。强制约束一定要放在可控的CLAUDE.md。