第 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上下文压缩和本章讲的记忆系统都涉及「保留信息」但它们是完全不同的东西维度/compact 上下文压缩记忆系统CLAUDE.md Auto Memory作用域当前会话跨会话整个项目或所有项目内容项目进度、已完成功能、待办事项技术栈、代码规范、偏好设置、经验教训生命周期会话结束即丢失持久化存储新会话自动加载谁来维护AI 自动生成摘要CLAUDE.md 由你手写Auto Memory 由 Claude 自动学习更新频率每个功能模块压缩一次项目规范变更时更新或 Claude 自动积累类比会议纪要这次会讨论了什么结论员工手册 团队知识库公司一直以来的规矩和经验一句话总结上下文压缩管「这次对话做了什么」记忆系统管「这个项目的规矩和经验是什么」。两者配合使用AI 才能既知道当前进度又遵守项目规范。3.2 记忆体系全景3.2.1 两大体系CLAUDE.md vs Auto Memory根据 Anthropic 官方文档Claude Code 的记忆系统分为两大体系CLAUDE.md 文件Auto Memory自动记忆谁写的你用户手动编写ClaudeAI 自动学习和记录内容性质指令和规则Instructions Rules经验和发现Learnings Patterns作用域项目级 / 用户级 / 组织级每个仓库per working tree / per repository加载方式每次会话启动时全量加载每次会话启动时加载前 200 行或 25KB其余按需检索典型内容技术栈、编码规范、构建命令、项目架构、硬性约定反复出现的构建命令、调试经验、踩过的坑、Claude 发现的偏好是否纳入 Git✅ 推荐纳入团队共享❌ 通常不纳入个人专属手动编辑建议经常编辑保持最新不建议手动编辑让 Claude 管理核心理解CLAUDE.md是你给 AI 下的「规矩」Auto Memory 是 AI 在工作中自己总结的「经验」。规矩是显性的、你主动制定的经验是隐性的、AI 被动积累的。3.2.2 CLAUDE.md 的三级作用域CLAUDE.md本身又分为三个级别按优先级从高到低级别文件位置作用域说明项目级project/CLAUDE.md当前项目项目特有的规范和约定纳入 Git 团队共享用户级~/.claude/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记忆类型可选值见下表四种记忆类型类型用途示例user用户身份、角色、偏好「用户使用 pnpm」「用户偏好 Tab 缩进」feedback用户给出的纠正和反馈「用户不喜欢 AI 主动解释基础概念」「用户要求注释用中文」project项目目标、约束、非代码事实「这个项目是内部工具不需要考虑国际化」「项目截止日期是 2026-12-31」reference外部资源链接「API 文档地址https://api.example.com/docs」「设计规范https://design.example.com」关联记忆使用[[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 文件 - 文件名组件用 PascalCaseUserTable.tsx工具函数用 camelCasedateUtils.ts - 提交信息遵循 Conventional Commitsfeat:, fix:, refactor:, docs:, chore: ## 重要约定 - **不要修改** frontend/src/generated/ 和 backend/src/generated/ 目录下的文件自动生成 - 环境变量通过 .env.example 声明实际值放在 .env已加入 .gitignore - 数据库迁移使用 pnpm db:migrate不要手动修改数据库表结构 - PR 合并前必须通过pnpm lint pnpm test pnpm build - 密码加密统一使用 bcryptsalt rounds 10不要使用其他加密方式 - API 返回格式统一为 { code: number, data: any, message: string }3.3.3 创建方式方式一手动创建直接在项目根目录创建CLAUDE.md文件按照上面的模板编写。这是最灵活的方式适合对项目已经很熟悉的情况。方式二/init 命令交互式创建/initClaude 会自动扫描项目文件提取以下信息技术栈从 package.json、配置文件中识别常用命令从 package.json 的 scripts 中提取项目结构扫描目录树现有规范从 ESLint、Prettier 配置中提取然后生成一份CLAUDE.md草稿你可以确认、补充和修改。这比从零手写高效得多推荐新项目使用。3.3.4 最佳实践✅ 应该做的保持简短建议不超过 200 行约 2K Token 以内。CLAUDE.md 每次会话全量加载越长越浪费上下文空间。写「约定」而非「文档」告诉 AI怎么做规则、约束、命令而不是是什么项目背景介绍、详细的功能说明。后者放在docs/目录中需要时 AI 可以按需读取。定期更新项目演进后技术栈变更、新增规范、目录结构调整及时同步更新 CLAUDE.md。过时的规范比没有规范更危险——AI 会按照旧规范生成错误的代码。信息密度高每一行都应该是 AI 需要知道的规则不要写废话。用列表和代码块少用大段文字。明确禁止事项把「不要做什么」写清楚如「不要修改自动生成的文件」「不要使用 any」「不要用 npm」。禁止事项比允许事项更重要。❌ 不应该做的不要把整个 README 复制进去README 是给人看的项目介绍包含大量背景信息AI 不需要这些。不要写 Claude 可以从代码中自动推断的信息比如「项目使用 React」——AI 看 package.json 就知道了不需要在 CLAUDE.md 里重复。但「必须使用函数式组件不要用 class 组件」这种约束是代码里看不出来的需要写。不要写临时信息「当前正在开发登录功能」这种临时状态不应该写在 CLAUDE.md 里它属于上下文压缩的范畴。CLAUDE.md 只写长期不变的规范。不要过于冗长地解释为什么简单说明规则即可不需要长篇大论解释背后的原因。比如「用 pnpm不要用 npm」就够了不需要解释 pnpm 的原理。3.4 Auto Memory 与独立记忆文件3.4.1 Auto Memory 是怎么工作的Auto Memory 是 Claude 的「自动学习」机制。在对话过程中Claude 会识别以下模式并自动写入记忆重复出现的命令如果你多次运行pnpm testClaude 会记住「这个项目的测试命令是 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 记忆的自动整合DreamsClaude Code 会定期运行「Dreams」机制类似人类睡眠时的记忆整合对记忆进行合并重复如果多条记忆表达相同内容合并为一条替换过时值如果新记忆覆盖了旧记忆更新为最新值提炼新洞察从多条记忆中提炼出更高层次的模式这个过程是自动的不需要手动干预。它确保记忆库不会因为长期积累而变得冗余和矛盾。3.4.4 独立记忆文件 vs MEMORY.md 汇总维度独立记忆文件MEMORY.md 汇总存储方式每个记忆一个文件带 frontmatter所有记忆汇总在一个文件中检索方式按 name 精确检索支持关联启动时加载前 200 行其余语义检索适合场景重要的、结构化的记忆零散的、短期的经验记录手动编辑可以但建议让 Claude 管理不建议手动编辑对于重要的、长期有效的记忆如「用户偏好 pnpm」Claude 会自动创建独立记忆文件对于零散的经验记录会写入 MEMORY.md。3.5 记忆管理四原则原则一不存代码能推导的信息项目结构、Git 历史、代码内容、依赖版本——这些信息 Claude 可以直接从文件系统中读取不需要存入记忆。记忆中只存「代码里看不出来的规则和经验」。❌ 不应该存项目使用 React 18package.json 里有 ✅ 应该存必须使用函数式组件 Hooks不要用 class 组件代码里看不出来 ❌ 不应该存测试命令是 pnpm testpackage.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 RouterPages 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 - 优先使用 pnpmAuto MemoryClaude 自动学习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 会加载用户级 CLAUDE.md个人偏好加载项目级 CLAUDE.md项目规范加载 Auto Memory 前 200 行经验教训按需检索独立记忆文件重要规则AI 从第一轮对话就知道你的所有规范和偏好不需要你重复说明。3.7 本章小结本章系统讲解了 Claude Code 的三层记忆体系核心知识点两大记忆体系CLAUDE.md你手写的指令与规则全量加载和 Auto MemoryClaude 自动学习的经验与发现启动加载前 200 行/25KB其余按需检索。前者是「规矩」后者是「经验」。CLAUDE.md 三级作用域项目级project/CLAUDE.md团队共享 用户级~/.claude/CLAUDE.md个人全局 组织级企业配置。高优先级覆盖低优先级。CLAUDE.md 最佳实践保持 ≤200 行约 2K Token写「约定」而非「文档」定期更新明确禁止事项。用/init命令可交互式创建。Auto Memory 机制Claude 自动识别重复模式、用户反馈、调试经验并写入记忆支持独立记忆文件带 frontmattername/description/type四种记忆类型user/feedback/project/reference支持[[slug]]关联定期通过 Dreams 机制自动整合。记忆管理四原则不存代码能推导的信息、不存临时信息、及时更新、定期审查。记忆 vs 上下文压缩记忆管「项目规矩和经验」跨会话持久化上下文压缩管「当前对话进度」会话内临时两者配合使用。下一章我们将进入代码回退与安全网学习如何在 AI 改崩代码时快速恢复以及如何构建多层级的回退机制。课后思考基础题CLAUDE.md和 Auto Memory 有什么本质区别分别由谁维护、加载方式有什么不同提示从「谁写的」「内容性质」「加载方式」三个维度对比。参考答案对比维度CLAUDE.mdAuto MemoryMEMORY.md谁写的用户手动编写维护由 Claude AI 自动学习生成用户尽量不手动编辑内容性质人为制定的指令、硬性规则、项目约定告诉AI必须怎么做属于项目的“宪法”AI在对话中沉淀得到的经验、踩坑记录、用户偏好、历史发现是AI总结出来的经验库加载方式每次会话启动完整全量加载会话启动仅加载前约200行25KB其余内容不会主动载入上下文需要的时候按需检索调取本质区别CLAUDE.md是人给AI下达的硬性约束指令具备强强制性Auto Memory 是AI自动归纳的历史经验沉淀不保证每次都能被读到。基础题CLAUDE.md 的三级作用域分别是什么优先级顺序是怎样的如果你想让团队所有成员都遵循同一个代码规范应该把配置写在哪一级提示考虑「团队共享」和「纳入 Git」两个关键词。参考答案三级作用域① 用户全局级~/.claude/MEMORY.md/ 用户全局配置作用于本机全部项目不会提交到Git②项目共享级项目根目录下CLAUDE.md作用域为当前整个项目可以纳入Git版本控制团队所有人clone项目后自动生效③ 项目本地级.claude/settings.local.json仅本机当前项目.gitignore忽略不团队共享优先级顺序项目本地级 项目共享级 用户全局级高优先级配置会覆盖低优先级同名配置。团队统一代码规范放置位置写在项目共享级的根目录CLAUDE.md。理由该文件可以纳入Git版本管理团队所有成员拉取代码自动获取统一规范全局级只作用个人本地级不会提交Git无法实现团队共享。进阶题CLAUDE.md 为什么要保持简短建议 ≤200 行如果项目规范很多写不下怎么办提示考虑 CLAUDE.md 每次会话全量加载的特性以及「详细文档放 docs/ 按需读取」的策略。参考答案为什么需要保持简短≤200行CLAUDE.md每一次会话启动都会完整全量加载进入上下文。行数越多占用token就越大直接挤占有效对话的上下文空间内容冗长会带来注意力稀释模型难以抓取关键硬性规则容易忽略重要约束增大幻觉概率文件过长修改、阅读、团队维护成本都会变高。规范多写不下的解决方案CLAUDE.md 只保留核心硬性约定技术栈、关键编码强制规则、启动命令、目录概要、最重要的安全约束把详细的长篇规范、架构文档、接口说明放到项目docs/文件夹作为独立Markdown文档在CLAUDE.md只写索引说明例如完整接口规范参见docs/api-spec.md复杂架构说明参见docs/architecture.md需要的时候再读取AI需要详细文档的时候按需让AI读取docs下的文件而不是会话一开始全部加载定期清理CLAUDE.md移除过时、不再生效的旧规则。进阶题记忆管理四原则是什么请判断以下信息应该存入记忆还是只放在当前对话上下文中(a)「项目使用 PostgreSQL」(b)「密码加密必须用 bcrypt salt rounds10」©「当前正在开发支付模块」(d)「Stripe SDK v14 有 bug锁定 v13.8.1」。提示用「代码能推导吗是临时的吗」两个问题来判断。参考答案记忆管理四原则不存储代码可以自动推导的信息代码、git历史能够读取得到的内容不要写入记忆不存储仅限本次对话的临时信息只在当前会话有效的临时任务、临时状态不持久化只存储长期稳定的事实、偏好、硬性约束定期审查记忆内容清理过时、失效信息。案例判断(a)「项目使用 PostgreSQL」存入记忆属于长期稳定项目事实代码无法一眼推导跨会话需要AI知道(b)「密码加密必须用 bcrypt salt rounds10」存入记忆长期硬性编码约束跨会话必须遵守©「当前正在开发支付模块」仅当前对话上下文属于临时任务状态任务完成之后就失效不需要跨会话记忆(d)「Stripe SDK v14 有 bug锁定 v13.8.1」存入记忆长期项目约束跨会话开发都要注意版本锁定属于稳定的踩坑经验。小技巧判断口诀是否长期有效跨重启会话AI是否需要知道代码能不能直接读出来临时状态不要存记忆。开放题Auto Memory 是 Claude 自动学习的你无法完全控制它记住什么、忘记什么。这种「不可控的自动学习」可能带来什么风险你会如何管理这些风险提示考虑记忆过时、记忆错误、记忆冲突、隐私泄露等可能性。参考答案潜在风险记忆过时风险项目迭代变更旧的业务规则、技术选型已经修改但Auto Memory还保留旧的历史记忆AI继续使用已经废弃的旧规则记忆错误幻觉记忆AI错误归纳对话内容生成不符合项目真实情况的错误记忆后续开发持续沿用错误信息记忆冲突同时存在多条相互矛盾的记忆模型不知道采信哪一条输出行为不稳定隐私与敏感信息风险对话中出现密钥、业务隐私、客户数据AI可能自动存入Memory造成敏感信息留存泄露关键信息丢失重要的硬性约束AI没有自动识别并保存跨会话直接遗忘不重要的冗余内容反而被大量占用记忆空间。风险管理手段关键硬性规则不依赖Auto Memory写进CLAUDE.md。把必须遵守的强制约定放在每次会话都会加载的CLAUDE.md作为最高优先级约束不交给自动记忆定期检查Memory内容手动删除过时、错误、冲突的记忆条目对话出现敏感信息之后明确告诉AI不要将以上内容保存到记忆规避隐私泄露重要决策完成之后手动把结论写入项目文档docs目录作为可信的信息源不完全依赖AI记忆新开会话时如果依赖历史经验可以主动让AI复述相关记忆校验记忆是否准确发现记忆错误立刻明确指令让AI删除错误记忆区分信息来源优先采信项目文档、CLAUDE.mdAuto Memory仅作为辅助经验参考不作为权威依据。补充Auto Memory定位是经验辅助不能当作权威配置文件使用。强制约束一定要放在可控的CLAUDE.md。