Claude Code记忆机制

Agent需要长期记忆
已有记忆机制的不足
[Claude Code的解法](#Claude Code的解法)
总结

Agent需要长期记忆

LLM 是无状态的。记忆机制的本质是给健忘的实习生"在工位上贴便签"。

规则类的信息需要跨会话个性化长期存储比如项目规范、用户偏好等，所以agent需要长期记忆机制。

已有记忆机制的不足

业界主流记忆方案都有不足，比如滑动窗口简单粗暴极易丢弃早期重要信息、摘要压缩会损失重要细节且有压缩成本、向量检索但是相似不等于相关可能召回无关噪音且维护成本高且向量形式不便于排查定位、分层存储（按重要性、频率和时间远近进行分层，近期常用核心信息常驻上下文，长期低频信息归档，按需向量召回）过于复杂且仍存在向量检索弊端。

以上方案共同病根是，记忆都是自由文本无约束，存储时不区分类型，无老化机制，重检索轻写入（该存什么不该存什么没有规定，garbage in garbage out）。

Claude Code的解法

Claude Code采用静态、动态两层记忆架构。

静态层是分层CLAUDE.md记忆文件，根据不同来源和可见范围分为用户级、项目级、系统级、ai自学等，存放稳定规则，按目录层级叠加诸如系统提示词。

动态层是如下流程：

当用户提问后，memories目录下MEMORY.md -- 一个记忆索引文件，相当于记忆目录，会被注入系统提示词

memories目录下存放的是一个个记忆文件+1个MEMORY.md索引，每个记忆文件都是md，头部信息frontmatter由name+description(决定召回场景)+type(四种记忆类型之一)，然后是记忆内容，最后还有记忆来源+适用场景，便于边界情况时判断是否使用。

同时会将所有md记忆文件前30行，涵盖frontmatter拼接后，由Sonnet廉价模型用Json Schema来挑出top-k相关的记忆，过滤掉最近出现的记忆和使用过的工具文档后，被注入记忆到系统提示词里，如果是2天前的记忆还会提醒模型去验证是否准确后再使用（老化机制）
在一轮对话结束后，Claude Code会触发stopHook去fork一个extractMemories代理复用prompt cache，然后去扫描历史信息尝试提取成值得写的四类记忆即用户画像（用户基本信息）、个人偏好、项目动态（项目当前状态）、外部指针（外部资源地址），在去掉已存在记忆后会写成记忆文件。

该存的四类记忆我们知道是什么了，Claude Code系统提示词明确指出不该存的有：可以grep得到的代码与文件、可以git log得出的git历史、临时状态，总之可以由代码推出来的内容不应存入记忆。

总结

简洁一点，Claude Code采用两层架构（CLAUDE.md静态文件+自动记忆动态层）、四种类型（用户画像、个人偏好、项目动态、外部指针，强制分类决策）、索引常驻（MEMORY.md索引始终加载、记忆内容按需加载）、小模型选择（sonnet当选择器、过滤已出现）、老化警告（2天前记忆提醒验证）。

可以迁移的设计原则，结构化分类记忆、索引常驻按需加载、小模型选top-k、老化机制逼模型主动验证。