Claude Code 记忆机制的核心设计理念在于，通过高度结构化的文本文件管理替代了业界普遍依赖的向量数据库检索方案，旨在解决传统记忆方案中“重检索、轻写入”导致的记忆质量失控问题。其架构围绕静态层与动态层两条主线展开，形成一套从规则定义到经验学习的完整闭环 。

一、静态层：声明式规则的多层级管理

静态层通过 CLAUDE.md 文件体系定义协作规范，其设计并非单一文件，而是细分为六个具有明确加载顺序与作用域的层级：

1. Managed 层：系统级强制策略，仅管理员可修改。
2. User 层：用户家目录下的全局个人偏好。
3. Project 层：项目根目录的团队共享规则，通常签入版本控制。
4. Local 层：项目根目录的个人本地规则，默认不纳入版本控制。
5. Auto 层：项目级自动记忆目录，由 Agent 自动写入。
6. Team 层：Auto 目录下的子目录，用于存储团队共享的、由 AI 学习到的偏好。

这六层规则在 Agent 启动时会被叠加而非覆盖地加载至系统提示词中。此外，静态层引入了 @include 指令以实现规则的模块化引用，以及条件规则机制，使得特定规则（如前端代码规范）仅在编辑相关文件时才被激活，从而有效节省上下文 Token 消耗 。

二、动态层：学习式经验的自动化闭环

动态层是 Agent 在交互中自动学习并应用经验的系统，其运作遵循一个严格的五步流程：

1. 记忆类型约束：为防止记忆库沦为“垃圾堆”，动态记忆仅允许四种结构化类型：

   • user：记录用户画像（如技术背景）。
   • feedback：记录行为偏好（如用户不喜欢回复后总结）。
   • project：记录项目动态（如代码冻结日期）。
   • reference：记录外部信息指针（如问题追踪系统位置）。
     其中，feedback 和 project 类型必须包含“规则内容”、“制定原因”及“生效条件”三元组，以确保规则的可解释性与边界清晰。同时，严禁存储可通过代码命令（如 grep, git log）直接推导出的信息，以避免产生“权威的错误” 。

2. 存储设计：每条记忆均为独立的 Markdown 文件，附带 YAML 头元数据。所有记忆文件的索引被汇总于一个 MEMORY.md 文件中。关键设计在于，仅将此索引常驻于系统提示词，而记忆的完整内容则按需加载，以此平衡记忆的可用性与上下文窗口的容量限制 。

3. 写入机制：记忆的抽取与写入由后台独立的轻量代理完成，而非在主对话过程中进行。该代理在每轮对话结束后启动，复用主对话的 Prompt 缓存以降低成本，通过扫描对话历史并与现有记忆比对，将新的有价值信息按上述四种类型分类并写入新文件 。

4. 检索策略：放弃向量相似度计算，采用小模型（如 Sonnet）进行自然语言选择。具体而言，将记忆的标题和描述拼接成清单，交由小模型直接选出最相关的若干条（如5条）。这种方法相比向量检索具有更好的可解释性，且在候选记忆数量有限（数百条）时，综合成本更低 。

5. 注入与验证：被检索出的记忆在注入上下文前，会被 <system-reminder> 标签包裹。更重要的是，系统会为超过特定时长（如5天）的记忆自动添加时效性警告，提示模型在使用前需主动验证其准确性。这一设计强制模型对记忆持怀疑态度，从根本上规避了基于过时信息做出错误决策的风险 。

三、总结：可借鉴的核心设计原则

基于上述机制，可提炼出四条普适的设计原则：

1. 结构化优于自由文本：为记忆定义严格的 Schema，强制包含类型、来源、置信度、更新时间等字段，避免非结构化文本导致的信息混乱。
2. 索引常驻，内容按需加载：在面对海量潜在参考信息时，让 Agent 通过常驻索引知晓“有什么”，仅在需要时加载完整内容，以优化 Token 使用效率。
3. 用廉价模型做选择题：在有限候选集内，使用小模型进行自然语言相关性判断，其准确性、可解释性和综合成本可能优于维护一个复杂的向量检索系统。
4. 时间感知与主动验证：为所有记忆附加时间戳，并对陈旧记忆添加显式警告，促使模型将其视为有待验证的历史快照而非绝对真理，从而保持决策的实时性与准确性 。

参考来源

• 别再只会用向量数据库了！Claude Code记忆机制源码级拆解