Claude Code 记忆机制深度拆解：从CLAUDE.md到Auto Memory的完整设计

从 Context 到 Memory：Agent 信息管理的两层边界

在构建 AI Coding Agent 的过程中，「记忆」始终是绕不开的核心命题。B站UP主在其源码分析视频中，系统性地拆解了 Claude Code 的 Memory 设计，为我们理解一个成熟 Agent 如何管理跨对话信息提供了绝佳样本。

要理解 Memory，首先要把它和 Context 区分开。Context 解决的是「当前这一轮模型能看见什么」的问题，它服务于单轮对话；而 Memory 要解决的是「本轮产生的信息中，哪些值得长期保留、未来什么时候需要重新取出」的问题。

在大语言模型（LLM）的技术体系中，Context Window（上下文窗口）是指模型单次推理时能够「看到」的全部文本长度，通常以 Token 数衡量（如 Claude 3.5 的 200K Token 窗口）。Token 是模型处理文本的最小单位，一个英文单词通常对应 1-2 个 Token，而一个中文字大约对应 1.5-2 个 Token。Context Window 的容量直接决定了模型在单轮交互中能处理的信息量上限。当对话内容超出窗口大小时，早期的信息会被截断或压缩，这就是为什么纯粹依赖 Context 无法支撑跨对话的长期记忆——每次新对话开始，Context 都是一张白纸。Memory 机制的核心价值正是突破这一限制，将重要信息持久化到模型外部，再在需要时重新注入 Context。

换句话说，Memory 是跨对话的信息，Context 是单轮对话的信息，二者有着明确的工作生命周期。完整的 Memory 链路可以概括为：本轮对话产生新信息 → 判断是否值得长期保留 → 选择作用域（生命周期）→ 写入持久化文件 → 建立轻量索引 → 未来检索并注入 Context → 验证、更新或删除。

两大稳定机制：CLAUDE.md 与 Auto Memory

Claude Code 目前稳定的跨对话机制主要有两种，它们在写入者、内容和加载方式上有本质区别。

CLAUDE.md：交给 Agent 的长期说明书

CLAUDE.md 是一类文件（而非单个文件），其写入者是用户、团队或组织，主要承载规则约定和项目的明确说明。它是一个分层的 Instruction Memory，在源码中的加载优先级从高到低依次为：

• Managed Memory：当前工作目录下的组织管理目录，第一优先级；
• User Memory：~/.claude/ 下的 CLAUDE.md，标记用户在所有项目中的个人偏好；
• Project Memory：根目录下 .claude/ 中的 CLAUDE.md，是整个项目共享的规则；Project Rules 则是按主题或目录拆分的详细版；
• Local Memory：CLAUDE.local.md，不进入版本控制的个人长期配置。

加载时，Claude Code 会从当前工作目录向上遍历，收集沿途所有名为 CLAUDE.md 的文件。当前目录下的直接加载，嵌套在深层目录中的则按需加载。它还支持通过引用引入其他文本文件、按主题拆分规则，或通过 path 前置说明绑定特定文件范围。开发者可以用 /memory 命令查看当前任务加载了哪些记忆。

需要特别注意的是，CLAUDE.md 是通过提示词影响模型行为的软性约束。如果任务需要硬性的边界和门禁，仅靠模型的指令遵循无法保证 100% 生效，往往需要通过代码脚本在 Runtime 层做硬控制。这一区分对工程实践至关重要：提示词层面的规则更像是「强烈建议」，模型在绝大多数情况下会遵守，但在复杂推理链或边界情况下可能出现违反。真正的安全边界——比如禁止删除生产数据库、禁止访问特定目录——应该通过操作系统权限、沙箱隔离或 CI/CD 流水线中的硬性检查来保障。

Auto Memory：Agent 自己积累的工作笔记

与 CLAUDE.md 不同，Auto Memory 由 Claude Code 的 Agent 自主写入（用户也可编辑）。在协作过程中，模型发现用户的偏好、反馈的错误或个人要求的规则，都会通过这种方式沉淀下来。

如果说 CLAUDE.md 是我们交给 Agent 的长期说明书，那么 Auto Memory 就是 Agent 在协作中形成的、对用户和任务理解的工作笔记。

Auto Memory 采用轻量索引 + 按需加载的两层结构：memory.md 是入口索引（类似目录），其中只保留简短的指针；真正的内容则分散在具体的主题文件中，点进去时才读取。一个 Git 仓库及其子目录会共享同一个 Auto Memory 目录。这种设计本质上是渐进式披露（Progressive Disclosure）策略在 Agent 记忆领域的应用——一种源自人机交互设计的经典方法论，核心思想是不一次性展示所有信息，而是根据当前需要逐层展开细节。如果把所有记忆文件在会话启动时全部加载进 Context，不仅会大量消耗 Token 配额（直接影响 API 调用成本），还会引入大量与当前任务无关的噪声信息，降低模型的推理质量。

源码中还能看到更细粒度的记忆类型：Session Memory（当前会话的状态、错误和下一步工作）、Agent Memory（某类子 Agent 被多次运行时积累的专项经验）、以及 Team Memory（跨用户、跨机器共享的团队级记忆）。

关于子 Agent（Sub-Agent），这是现代 AI Agent 架构中的一种重要设计模式：主 Agent 在执行复杂任务时，将特定子任务委派给专门的轻量级 Agent 处理。这些子 Agent 通常拥有更窄的权限范围和更专注的系统提示词，以保证执行效率和安全性。Agent Memory 正是基于这种模式——当某类子 Agent（如负责测试的 Agent）被反复调用时，它会积累关于特定任务类型的经验，形成专项记忆。

Memory 的五阶段生命周期

一条记忆从诞生到消亡，会经历筛选、存储、检索、注入、维护五个阶段。

筛选写入：谁来决定这件事值得记

源码中存在三条写入路径：

1. 用户明确写入：手动编辑 CLAUDE.md、使用 memory 命令或直接要求模型记录；
2. 主 Agent 主动写入：Agent 在执行任务时发现可长期复用的信息，高度依赖其语义理解能力；
3. 后台提取：一轮 Core Loop 结束后，由专门的子 Agent 筛选候选记忆。

这里提到的 Core Loop（核心循环）是 AI Agent 的基本运行范式，通常遵循「感知—思考—行动—观察」的迭代结构。在 Claude Code 中，Agent 接收用户指令后，会反复调用工具（如读写文件、执行命令、搜索代码）并根据工具返回结果决定下一步操作。每一轮循环中，Agent 将工具调用结果追加到 Context 中，再请求模型生成下一步行动，直到判断任务已完成或需要用户进一步输入。理解这一点有助于理解为什么记忆的「后台提取」安排在循环结束后——它不干扰主任务的执行流程。

其中第三条在当时的源码中属于实验路径，权限较窄（大致只读），但它揭示了一个重要的前台-后台分离思路：主 Agent 负责完成任务，后台子 Agent 负责记忆的更新与维护。这种「写入与执行解耦」的架构，与微服务设计中的职责分离原则一脉相承——既避免了主 Agent 因记忆管理分心而影响核心任务质量，又通过权限隔离降低了记忆被误写或污染的风险，是后续 Agent 设计的明确趋势。

存储组织：按主题的自然语言结构

由于 Agent 能力强依赖模型，而模型最擅长自然语言理解，因此 Memory 用自然语言组织并按主题分类（如 Project Rules 归为一类）。存储时有几条关键约束：

• 写入前检查重复，避免重复内容被反复加载、重复消耗 Token；
• 优先更新已有文件，再考虑新建；
• 保持 Description 准确，因为系统是「先索引后加载」，描述的精度直接决定检索精度。

检索与注入：让记忆进入 Context

启动一轮会话时，系统会先读取索引、明确当前有哪些主题，再根据任务相关性 read 对应文件。源码中有一个特别的 Feature Flag 控制相关性预取：它会扫描 Memory 文件的 Front Matter（前置说明），收集文件名、description、时间，最多预取五个作为 attachment 提供给模型选择。

Feature Flag（功能开关）是软件工程中广泛使用的一种配置化发布机制，允许开发团队在不修改代码和重新部署的情况下，动态启用或禁用特定功能。在 Claude Code 的源码中，Feature Flag 被用于控制实验性功能的灰度发布，例如这里的「相关性预取」策略。通过 Feature Flag，Anthropic 团队可以针对不同用户群体逐步开放新功能，同时快速回滚出现问题的特性。值得注意的是，Feature Flag 在记忆维护中还有一个特殊用途：Agent 在验证旧记忆是否仍然有效时，会检查记忆中引用的 Feature Flag 是否仍然存在于当前代码中——如果某个 Feature Flag 已被移除，依赖它的记忆很可能已经过期。

而 Front Matter（前置说明）是一种在 Markdown 文件顶部嵌入结构化元数据的约定格式，通常用三条短横线（---）包裹，内部采用 YAML 语法。在 Claude Code 的记忆系统中，Front Matter 被用来存储记忆文件的 description（描述）、创建时间、关联的文件路径等元信息。系统在决定是否加载某个记忆文件时，不需要读取文件全文，只需扫描 Front Matter 中的描述即可判断相关性。这种设计本质上是一种轻量级的语义索引——用极小的 Token 开销换取对大量记忆文件的快速筛选能力。

这里有一个关键认知：磁盘里保存了一条 Memory，不等于它会被使用到。Memory 属于模型外的持久化状态，必须经过发现、选择、读取、包装、注入五步，才能影响当前决策。注入时机通常有两个——启动时加载 CLAUDE.md 和 rules，以及过程中按需加载嵌套文件。

维护更新：把 Memory 视为可漂移的证据

Memory 会老化，因此维护环节至关重要。源码通过 Memory Prompt、alias 和 Feature Flag 三种方式管理：在使用召回结果前，Agent 需要检查路径是否存在、函数与 Feature Flag 是否仍在源码中、当前配置是否变化、记忆是否与本轮观察冲突。

核心原则是：当前证据拥有更高优先级。最新信息会覆盖旧记忆，一旦发现错误或过期内容，Agent 应主动更新或删除对应的 Memory。这一原则在实际开发中的重要性怎么强调都不过分——代码库是一个持续演化的实体，API 接口会变更、依赖库会升级、架构模式会调整。一条三个月前记录的「项目使用 Webpack 打包」的记忆，可能在团队迁移到 Vite 之后变成误导性信息。如果 Agent 盲目信任旧记忆而不与当前代码实际状态核对，可能会产生严重的错误决策。

Claude Code 记忆设计的五个精髓

综合来看，Memory 之所以能让 Claude Code 表现出色，源于五个设计特点：

1. 文件系统提供可解释性：无论 Context 还是 Memory，结构和边界都很清晰——哪些由用户维护、哪些由前台写入、哪些由后台提取一目了然，且可进入版本控制。版本控制（如 Git）在这里扮演着重要角色：CLAUDE.md 和 Project Rules 等文件被设计为可纳入 Git 仓库管理，每一次规则变更都会留下完整的修改记录——谁改了什么、什么时候改的、改动原因是什么。而 CLAUDE.local.md 被明确排除在版本控制之外（通常通过 .gitignore），因为它承载个人偏好和本地环境配置，不应影响团队其他成员的 Agent 行为。这种「共享规则进版本控制，个人配置留本地」的设计，体现了对协作边界的精细考量。对于 Coding Agent 而言，可观测性和可审计性本身就是核心能力。
2. 索引 + 主题文件控制 Context 窗口：即贯穿始终的渐进式披露策略。
3. 作用域表达 Memory 所有权：个人偏好、rules、长期配置等不同类型，写入时必须明确作用域，选错会显著影响记忆质量。
4. 写入与执行解耦：主 Agent 完成任务，子 Agent 负责记忆维护，这是未来 Agent 架构的演进方向。
5. Memory 被视为可漂移的证据：源码加入修改时间、过期检查、冲突处理等一整套维护机制。

因此，评估一个 Agent 的记忆能力时，不能只看「能不能记」，更要看它的纠错与怀疑能力——是否能识别错误记忆并及时更新。

落地思考：需要警惕的六类风险

对于打算自研 Agent 记忆系统的开发者，视频最后总结了需要针对性处理的风险点：写入错误、过度保存、召回遗漏、召回噪声、数据漂移、隐私风险以及 Token 成本。不同业务场景对这些风险的敏感度不同，例如垂域模型对可审计性要求更高，就需要对相应环节做单独设计。

其中 Token 成本这一项值得展开说明：在 API 调用模式下，每次将记忆内容注入 Context 都会产生实际的 Token 消耗。以 Claude 3.5 Sonnet 为例，输入 Token 的定价约为每百万 Token 3 美元。如果一个项目积累了数十个记忆文件，每次会话启动时不加甄别地全部加载，可能会在还未开始处理用户实际任务之前，就消耗掉数千乃至上万个 Token。这就是为什么 Claude Code 的「先索引后加载」和「最多预取五个」的设计如此重要——它们本质上是在记忆召回质量与 Token 经济性之间寻找最优平衡点。

而隐私风险则涉及另一个维度的考量：Auto Memory 会自动记录用户的偏好和工作模式，在团队协作场景中，如果 Team Memory 的边界控制不当，个人的编码习惯、常见错误甚至项目的敏感架构信息都可能被不恰当地共享。对于金融、医疗等受监管行业，记忆系统中存储的信息还可能涉及合规要求，需要在设计阶段就纳入数据分级和访问控制机制。

理解 Claude Code 这套「轻量索引 + 渐进式披露 + 前后台解耦 + 证据漂移管理」的记忆哲学，不仅有助于回答 Agent 架构相关的技术问题，更能为自己动手构建生产级 Agent 提供一套经过实战验证的设计范式。

核心要点