Claude Code 记忆机制

原链接：Claude Code 六层记忆体系

一、核心思路

Claude Code 的记忆不是单纯保存聊天记录，而是把规则、会话、任务进度、长期经验和历史摘要分别管理，在有限的上下文窗口内维持工作连续性。

需要区分：信息保存在文件中，不代表模型当前就能看到；只有被加载或召回到当前上下文中的信息，才能直接参与本次回答。

二、六层记忆分别做什么

层级	解决的问题	主要内容或载体	生命周期
① 指令记忆	应该怎么做？	CLAUDE.md，保存用户偏好、项目规范等	长期有效，按作用域加载
② 短期会话记忆	刚才发生了什么？	当前对话、工具调用及结果	当前会话
③ 工作任务记忆	任务做到哪里了？	目标、进度、中间结论、失败尝试、待办事项	当前任务
④ 长期记忆	以后还需要记住什么？	MEMORY.md、主题记忆文件等	跨会话持久保存
⑤ 摘要记忆	上下文太长怎么办？	会话摘要，文中称 session-memory.md	会话内持续更新
⑥ AutoDream	长期记忆积累后怎么整理？	对已有长期记忆去重、合并、更新和重建索引	空闲或后台执行

1. 指令记忆：保存行为规则

文章将指令划分为组织、用户、项目、本地四个作用域，用于组合统一规范和局部需求。

对于目录中的指令文件，文章描述的加载方式是：

从当前目录向上查找
        ↓
收集沿途的指令文件
        ↓
从上层目录到当前目录依次加载

CLAUDE.md 提供用户或项目要求，系统提示词提供 Agent 内建的行为规范，两者共同影响执行。

2. 短期记忆与任务记忆：分别保存对话和进度

• 短期会话记忆保存“刚才说了什么、调用了什么工具”，受上下文窗口和 Token 预算限制。
• 工作任务记忆保存“已经完成什么、还剩什么、下一步做什么”，帮助长任务持续推进。

任务中的临时状态不必全部永久保存，具有复用价值的结论才适合进入长期记忆。

3. 长期记忆：提炼经验，按需读取

文章把长期记忆分为四类：

• User：用户偏好、习惯、工作风格。
• Feedback：用户纠正，以及得到认可的做法。
• Project：项目长期背景、约定和特殊约束。
• Reference：文档、知识库、代码仓库等外部资料的位置。

长期记忆通过索引和相关性判断按需召回，避免把所有内容一次性塞进上下文。外部知识也可以只保存查找入口，需要时再读取。

文章还描述了由独立后台 Agent 提炼和写入记忆的方式，并强调并发写入需要防止覆盖和更新丢失。

三、摘要与上下文压缩如何配合

这是文章最重要的机制区别：

后台更新摘要，不等于立即压缩当前上下文。

对话持续增长
    ↓
后台增量更新会话摘要
    ↓
主上下文接近容量限制
    ↓
触发 Compact
    ↓
用“历史摘要 + 最近原始消息”组成较小的上下文
    ↓
继续对话，之后再次压缩

摘要更新利用“已有摘要 + 新增消息”，不必每次重新总结全部历史；由于后台处理是异步的，摘要进度可能落后于当前对话。

Compact 保留最近原文，是为了减少摘要造成的细节损失。因此，整体规律是：较早的信息更抽象，最近的信息更完整。

文章中的数字分别表示：

数值	文中含义
10K tokens	首次建立会话摘要的门槛
新增约 5K tokens	后续摘要更新的条件之一
约 187K tokens	200K 窗口示例中的自动压缩触发点
最多约 40K tokens	压缩时保留最近原始消息的上限

这些是文章所述版本或配置中的参数，不能视为固定不变的产品规则。

四、三种后台工作要分清

机制	主要职责
Session Memory	总结当前会话，支持上下文压缩
Memory Extraction	从对话中提炼值得跨会话保存的新知识
AutoDream	整理已有长期记忆，处理重复、冲突和过期内容

它们分别对应：压缩历史、积累经验、整理经验。

五、记忆与缓存的区别

记忆负责保存和组织信息；缓存负责减少重复处理。

文章区分了本地读取缓存、会话状态复用，以及模型/API 层的 Prompt Cache。其中：

• Claude Code 负责组织上下文，让稳定内容形成可复用的输入前缀。
• 模型/API 层负责判断 Prompt Cache 是否命中。
• 缓存命中不会缩小上下文占用；真正释放上下文空间的是 Compact。
• 本地缓存是否仍然有效，需要额外的失效与一致性机制来判断。