04Memory SystemClaude Code 如何把经验变成可召回知识上一篇把 Prompt System 理解成 Claude Code 的行为协议装配层。提示词系统解决的是“本轮 agent 应该按什么身份、规则和工具契约行动”。但长期协作里还有另一个问题有些信息反复出现用户不想每次都重新解释agent 也不该每次都重新踩坑。这就进入 Memory SystemClaude Code 如何判断什么值得被记住并在后续任务里把它重新召回这篇拆的是一条信息管道一条信息从当前会话出现到成为可复用记忆再到下一次进入模型上下文中间到底发生了什么。这篇文章要拆的主线什么值得被记住这一篇回答的问题是Claude Code 如何把一次任务里的经验筛选成后续任务可召回的项目知识、用户偏好、调试经验和会话状态这里的关键词是“筛选”。一次会话会产生很多信息用户要求、工具结果、报错日志、文件改动、计划变化、测试结论、临时限制、用户纠正。它们都可能有用但生命周期完全不同。有些信息只对当前任务有用比如“这次先别跑全量测试”。有些信息适合变成项目规则比如“这个仓库使用 pnpm”。有些信息适合变成调试经验比如“构建报错经常来自 frontmatter 字段”。有些信息应该交给运行时硬边界比如“禁止读取密钥文件”。所以记忆系统的核心不是“全都记住”而是判断这条信息应该留在哪一层什么时候再拿出来这就是 memory router 的问题。记忆系统解决的工程问题把经验变成可召回知识长任务和长期协作里最烦人的成本往往来自重复补背景同样的命令、同样的偏好、同样的环境坑隔几天又要解释一遍。比如用户每次都要提醒“这个项目用 pnpm”。agent 每次都要重新找构建命令。某个本地服务没启动导致测试失败下一次又踩一遍。写同一系列文章时口吻、引用方式、章节边界反复被纠正。恢复一个旧任务时前面做过什么、还剩什么已经散在聊天历史里。记忆系统要减少这些重复摩擦。它的价值不是让模型拥有神秘的长期大脑而是把有复用价值的信息文件化、索引化再在合适时机重新装进上下文。用一句话概括Memory System 把一次任务里的可复用经验变成后续任务可以召回的外部知识。这个定义也把它和 Prompt System 分开了。提示词系统负责本轮行为协议记忆系统负责跨会话保存可复用信息。至于每一轮到底加载哪些记忆、放到上下文哪里第 05 篇上下文管理再展开。记忆不是一个文件而是几层状态Claude Code 的记忆更像几层不同生命周期的信息而不是单独一个“memory 文件”。可以先看一张地图信息层主要内容生命周期适合解决什么问题session transcript本次会话消息、工具调用、结果、任务状态当前 session 或恢复同一 session继续之前那件事CLAUDE.md/ rules人维护的项目规则、命令、约定项目长期存在团队共享和版本管理MEMORY.mdindexauto memory 的入口索引本机项目长期存在快速告诉 agent 有哪些可查记忆topic files调试经验、偏好、项目细节等专题记忆按需读取需要细节时再展开team memory团队共享的长期知识团队范围多人、多环境共享经验runtime policysettings、permissions、hooks长期硬约束动作许可、拦截、审计这里最容易混的是CLAUDE.md和 auto memory。CLAUDE.md更适合放人明确维护的项目规则比如常用命令、目录约定、生成文件规则。它适合被团队 review也适合随仓库版本变化。auto memory 更像 Claude 从使用过程中提取的笔记。它可能来自用户纠正、偏好、调试经验和项目模式通常更偏个人或本机项目上下文。runtime policy 又是另一层。settings、permissions、hooks 可以跨会话生效但它们不是“给模型读的软知识”而是运行时硬约束。比如禁止读密钥文件更适合放到权限规则里而不是只写成记忆。这样分层以后记忆系统就不再是“往哪里写一段话”而是“这段信息属于哪种状态”。MEMORY.md索引而不是仓库全集auto memory 里最值得注意的是MEMORY.md。它不是把所有长期经验都塞进去的大文件更像一个入口索引。启动时Claude Code 会加载有限的MEMORY.md内容让模型知道有哪些主题值得查。更细的内容会拆到 topic files需要时再读。Mem0 的分析提到MEMORY.md有前 200 行或 25KB 这类加载限制详细记忆会按主题拆到其他文件Claude 后续可以再读取相关 topic files。[2]这说明 memory 的设计很克制启动时先给索引需要细节时再读正文。这个设计和上下文管理的思路是一致的。启动时把所有记忆全量塞进去成本高噪声也大。索引短一点topic files 分开agent 才能按任务需要取信息。这也带来一个要求索引要写得像索引。好的MEMORY.md应该让 agent 一眼知道有哪些主题文件。每个主题大概解决什么问题。哪些记忆最近更新。哪些信息可能过期需要复核。如果索引只是堆很多散句Claude 可能知道“有很多记忆”却不知道该打开哪一份。Milvus 对 memory 限制的讨论也提醒了一点长期项目里记忆会积累索引上限、召回方式和旧信息污染都会变成问题。[4]所以 memory 的第一条工程原则是记忆要能被找到比记忆多更重要。记忆如何写入从用户纠正到后台提取记忆写入大概有几条路径。第一种是用户显式要求。用户说“记住这个项目以后都用 pnpm”这类信息适合进入长期记忆。用户说“把这条写进项目规则”那更适合进入CLAUDE.md或 rules。第二种是用户反复纠正。如果用户多次纠正“写这个系列时中文为主”“少用反驳式表达”“不要写硬核源码逐行解读”系统就可以判断这里有稳定偏好。稳定偏好适合沉淀临时限制则留在当前任务里。第三种是人主动维护项目规则。团队可以手动更新CLAUDE.md、rules 或项目文档。这类写入更适合团队共享也更适合代码 review。项目命令、目录约定、生成文件规则通常应该走这条路。第四种是后台提取。Mem0 和 win4r 的分析都提到Claude Code 的 memory 并不只是手写文件还涉及从会话中提取候选经验的机制。[2][3]这类后台提取的价值是省心用户纠正过的偏好、项目里的反复坑、调试经验可以被整理成未来可读的 markdown。但它也需要审计。一次临时要求可能会被误判成长期偏好。比如“这次先别跑全量测试”可能只是当前任务为了节省时间如果写成长期记忆后面每次验证都可能变弱。所以自动写入要配一个出口用户能看到、能改、能删。/memory或文件层面的审计入口正是这类系统能长期使用的关键。记忆如何召回启动加载、按需读取、恢复会话写入只是前半段召回才决定记忆能不能帮上忙。记忆召回可以分成三种场景。新 session 启动。启动时加载稳定记忆和索引比如人维护的项目说明、规则以及 auto memory 的入口索引。它们给模型一个默认背景。按需读取细节。当任务触发某个主题Claude 可以再读 topic files。比如构建失败时读取调试经验写博客时读取写作偏好改 API 时读取接口约定。恢复同一会话。恢复 session 时带回 transcript这是“继续之前那件事”。它和长期项目记忆不同更多是当前任务的历史状态。这三种召回经常被混在一起。比如 session transcript 里有一个临时计划它可以帮助恢复当前任务但不应该自动变成项目长期规则。CLAUDE.md里的测试命令适合每次新会话都加载。topic memory 里的某个调试经验只在相关任务里读取就够了。所以召回的核心是时机新会话给稳定背景当前任务读相关细节恢复会话带回工作现场。05 上下文管理会继续讲这些召回来的东西进入上下文以后还要面对顺序、长度、压缩和污染问题。记忆应该按用途分层偏好、约定、经验、交接为了避免文章滑进源码字段我更愿意按用途给记忆分层。用途例子更适合放哪里用户偏好喜欢先给结论、中文为主、少写反驳句auto memory 或用户级规则项目约定使用 pnpm、目录结构、生成文件不要手改CLAUDE.md/ rules调试经验构建失败常见原因、本地服务依赖、测试坑topic memory任务交接已改文件、未跑验证、下一步计划session transcript、notes、compact summary硬边界禁读密钥、危险命令审批、工具审计settings、permissions、hooks这个分类更贴近日常工程。它也能帮助判断一条信息的归宿。“这个系列文章主要用中文写”是用户偏好和项目约定的混合如果只对这个博客系列生效可以写进项目写作规则或改造计划。“本轮先不跑构建”是任务交接不适合长期记忆。“构建报错经常来自 frontmatter 字段缺失”是调试经验适合进 topic memory。“不要读取.env”是硬边界适合权限配置。这就是记忆路由。对我写 Agent 的启发设计 memory router如果自己写一个 coding agent我会先设计 memory router而不是先设计 memory database。数据库只是存储。真正决定效果的是路由。我会把流程拆成六步捕获。从用户纠正、工具结果、失败日志、文件改动、总结里收集候选记忆。分类。判断它是用户偏好、项目约定、调试经验、任务交接还是运行时硬边界。写入。不同类型写到不同位置rules、topic memory、session notes、permissions、hooks。召回。新会话加载稳定索引当前任务按需读细节恢复会话带回 transcript。审计。用户能看到记忆来源、更新时间、适用范围和当前内容。遗忘。过期、错误、临时信息要能删除或降级。每条 memory candidate 都要问几个问题它从哪里来作用域是用户、项目、目录、任务还是团队有效期大概多久应该写到哪里什么时候召回谁能审计和修改这套问题比“存进向量库还是 markdown”更基础。Claude Code 给我的启发是记忆系统不一定一开始就很复杂但它必须可见、可分层、可修剪。否则 agent 记得越多越容易带着错误背景行动。参考资料Claude Code 记忆系统[1] How Claude remembers your project - Claude Code Docs本文主要参考它关于CLAUDE.md、auto memory、MEMORY.md、topic files、加载顺序和/memory审计入口的说明。[2] How Memory Works in Claude Code - Mem0本文主要参考它关于MEMORY.md索引、200 行 / 25KB 上限、topic files、freshness warning 和后台提取机制的分析。[3] Claude Code 记忆系统深度分析 - win4r/cc-notebook本文主要参考它关于 session memory、persistent memory、team memory 的分层分析。[4] Claude Code Memory System Explained: 4 Layers, 5 Limits, and a Fix - Milvus本文主要参考它关于 memory 限制、召回失败、索引上限和长期污染风险的讨论。[5] Claude Code Source Leak: The Three-Layer Memory Architecture - MindStudio本文主要参考它从 builder 视角对三层记忆架构的总结。下一篇Context Management这一篇先把 Memory System 理解成 Claude Code 的记忆路由系统。核心结论是记忆系统的关键不是记得越多而是把信息写到合适的层并在合适时机召回。但记忆被保存以后还有一个问题每一轮模型调用时到底加载哪些记忆、工具结果和项目材料它们进入上下文后怎么排序、压缩、隔离所以下一篇继续追的问题是Claude Code 如何管理进入模型上下文的信息让 agent 看见关键东西同时控制噪声