一：长期记忆层（跨会话持久化）
作用：保存跨会话的持久化知识，作为 AI 行为的长期指引。
1.CLAUDE.md（项目宪法）
①性质与作用：手动编写的静态规则文件。定义项目核心规范、技术栈、编码风格等，作为 AI 的基础行为准则。
②作用域：支持四级：企业级 > 用户级 > 项目级 > 本地级。若多个层级同时存在，高优先级会覆盖或合并低优先级（具体取决于配置）。这让你可以在公司统一规范和个人偏好之间灵活平衡。
③加载方式：每次会话启动时，内容注入到第一条用户消息前，确保 AI 从开始就理解项目偏好。
2.Auto Memory / MEMORY.md（自动记忆索引）
说明：AI 自动生成的“工作笔记”，不是大内容文件，而是索引文件（类似目录卡片）。实际记忆内容存放在独立 .md 文件中。容量限制：前 200 行 / 25KB 以内，控制上下文开销。
2-1更新机制
①更新方式与时机：主 Agent 完成回复后，系统会根据预置触发条件（见下一条）判断是否需要更新记忆。若需要，则启动一个后台子代理（Forked Agent）自动提取记忆，该子 Agent继承父对话的 prompt cache来降低成本，被严格限制为只读当前项目文件，只写memory目录，最多执行 5 轮操作。
②更新触发条件（满足任一即触发）：
-累计 token 数超过 10000；
-距上次提取新增 token 超过 5000；
-距上次提取的工具调用超过 3 次；
-最近一轮没有工具调用
2-2召回机制
①召回记忆文件结构：每个记忆文件是一个独立的 Markdown 文件，其结构严格分为两个部分：
YAML Frontmatter：位于文件顶部，包含name、description、type等信息。内容仅供系统/模型读取，用于快速筛选。其中类型type包括四部分
- type: user：用户手动维护的个人长期记忆、偏好、个人规范
- type: feedback：AI 自动从对话中提炼的反馈、结论、经验教训
- type: project：项目级规则、技术栈、编码规范、项目宪法（对应 CLAUDE.md）
- type: reference：参考资料、文档、外部知识、业务背景
Markdown 正文：Frontmatter 之后的内容，是人类可读的记忆详情，也是最终会加载到上下文中的具体信息
②召回过程：每个记忆文件头部包含 YAML Frontmatter（name、description、type）；用户提问时，专门模型读取所有记忆文件的 Frontmatter 进行语义匹配，筛选出最多 5 个最相关的文件；将这些文件的详细内容加载到当前会话上下文。
步骤一：读取全量索引：会话启动时，MEMORY.md 被完整加载到上下文中。该索引文件包含了所有记忆文件的文件名、描述、类型、时间戳等关键元数据。
步骤二：执行语义匹配：当用户提出新问题时，一个专用的模型（通常是 Sonnet）会被调用。该模型的工作是：将用户当前的查询意图，与索引中所有记忆文件的元数据（主要是 description）进行语义比对，从而筛选出最相关的记忆文件。注：Sonnet 模型是作为「相关性判断引擎」而非「相似度计算器」（即RAG中的精排，原因是精排模型只能计算“相似”，无法真正“理解”）来工作的。 这个过程更像在模型在做一个智能决策：模型不会计算问题与记忆之间的数学相似度，而是理解问题的意图，然后在所有记忆中挑选出最相关的。即会同时看 name/description/type。
步骤三：加载正文内容：模型筛选出相关性最高的最多 5 个记忆文件后，系统会找到这些文件并加载其完整的 Markdown 正文，注入到当前会话的上下文中。
③召回频率：每次用户提问都会触发。
2-3总结：Claude Code 的 Frontmatter 机制，本质上是一套 “先有索引，后取正文” 的两阶段召回系统，其设计核心是在“智能”和“成本”之间取得了务实的平衡。
高性价比的检索：通过轻量级的索引和大模型语义匹配，在不引入昂贵向量数据库的情况下实现了高质量召回。
严格的成本控制：通过限制索引大小、按需加载正文、后台 Fork 继承缓存等方式，严格控制 Token 开销。
高透明度：所有记忆都以可读的 Markdown 文件存储在本地，便于用户随时查看、手动编辑或删除。
与技能系统类似：这种 Frontmatter + Markdown 的结构，与 Claude Code 的技能（Skill）系统 定义方式如出一辙，体现了其系统设计的一致性。
二：当前轮召回层（会话内上下文管理）
性质与作用：管理当前会话的上下文动态，不负责长期存储。包含两个核心功能
功能一：加载相关记忆：根据用户提问，从第一层的长期记忆中召回最相关信息（通过 Frontmatter 语义匹配），注入当前对话。
功能二：会话内压缩（Session Memory），当对话过长时，自动压缩历史，节省上下文窗口。生成摘要文件 summary.md，仅服务于当前会话，不跨会话。两种压缩方式。
1.第一个压缩策略：Session Memory 压缩（优先尝试），压缩触发时检查 Session Memory 是否可用。若可用，直接使用其内容作为摘要，不调用 API。
①性质与作用：保留近期消息，Session Memory 后台维护 lastSummarizedMessageId，标记已提取到的位置。该标记之后的近期消息原封不动保留。最低保护：至少保留 5 条消息、至少 1万 tokens。模型最终看到Session Memory 摘要 + 保留的近期消息
②更新方式：Session Memory 的核心，是在后台维持一份结构化的 Markdown 笔记文件，记录会话中的关键信息（例如：当前任务、重要文件、已发生的错误与修正等）。笔记模板固定包含约 10 个 Section，每个 Section 有大约 2K token 的上限，整个文件上限约为 12K token，以控制成本。让一个后台 Forked Agent 拿着这份笔记文件，调用编辑工具（read_file、edit_file等工具）原地更新，且严格遵守 “不能增删 Section 标题，只能修改 Section 内容” 的约束
③更新触发逻辑（基于活动量的智能触发）：Session Memory 的更新是非阻塞的。其更新 Agent 注册在 postSamplingHook（即每次模型采样后）触发。核心判断逻辑来自shouldExtractMemory函数来判断活动量，它像一个“调度官”，只有当对话上下文积累到一定程度时，才会下达提取指令。此外，Session Memory 的提取过程设有锁机制（markExtractionStarted/completed），确保同时只有一个提取任务在进行。
④更新触发条件：
- 首次触发：会话累积Token数首次超过约 10,000 时。这确保了模型在提取前已有足够的信息进行总结。
- 增量触发：自上次提取后，新增Token超过约 5,000 时。这确保了记忆能随对话进展而持续更新。
- 工具触发：自上次提取后，工具调用次数超过 3 次时。这通常是关键操作发生的信号，触发了提取需求。
- 自然断点：最近一轮对话中没有工具调用。这个条件用于判断对话是否进入了一个“间歇期”或“思考阶段”，适合进行记忆整理。
⑤总结：使用以下三种措施来控制token消耗
- 措施一：被动触发，而非实时循环：Session Memory的提取并非每轮对话都触发，而是由shouldExtractMemory函数判断是否达到“自然断点”，例如新消息超过约10,000 tokens或多次工具调用后。这种有选择的低频触发从源头上减少了不必要的API调用。
- 措施二：成本复用 (KV Cache Hit)：这是降低成本的核心机制。Forked Agent会继承父对话的Prompt Cache，意味着在生成记忆时，它复用了父会话已有的计算结果，无需为理解庞大的对话上下文支付高昂的重复计算成本。这种“站在巨人肩膀上”的方式让每次提取的成本被大幅均摊。
- 措施三：限制作业范围：为确保安全与效率，Forked Agent被严格限制仅能编辑指定的会话笔记文件。这种限制简化了任务，避免了在无关文件上产生意外开销。
2第二个压缩策略：标准压缩（回退方案）。当 Session Memory 不可用时（例如手动压缩时用户提供自定义指令），调用一次 API，让模型阅读完整对话历史并生成一段摘要。所有消息被替换，不保留任何近期消息，模型最终看到仅摘要。
①更新触发条件：有效上下文窗口大小 - 13000 缓冲 token。例如 200K 上下文模型，约在 167,000 tokens 时触发。连续失败 3 次后停止尝试（熔断器），避免无限循环。
三：会话持久层（对话日志存储）
①性质与作用：完整、永久保存整个会话过程的原始记录。
②实现方式：所有对话以 .jsonl（JSON Lines）格式完整保存，一般保留 30 天。通常位于 ~/.claude/sessions/。
③关键区别：这是无损的完整对话日志，可通过 /resume 命令恢复之前的会话。
四：总结图示
┌─────────────────────────────────────────────────────────────┐
│ 第三层：会话持久层（原始日志） │
│ .jsonl 完整对话记录 → 作为 feedback 记忆的数据源 │
└───────────────────────┬─────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 第一层：长期记忆层（跨会话持久） │
│ ├─ CLAUDE.md 系列 → type: project（静态规则，四级优先级） │
│ └─ MEMORY.md + 分散记忆文件 │
│ ├─ type: user （用户手动长期记忆） │
│ ├─ type: feedback（AI 自动沉淀经验） │
│ └─ type: reference（参考资料知识库） │
└───────────────────────┬─────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 第二层：当前轮召回层（会话内动态管理） │
│ ├─ 智能召回：每次提问 → 匹配四种 type 记忆 → 注入上下文 │
│ └─ 会话压缩：Session Memory / 标准压缩 → summary.md │
└─────────────────────────────────────────────────────────────┘
哲学视角
“记忆不是负担，而是阶梯。”
—— 三层设计将记忆拆解为沉淀（会话日志）、索引（长期记忆）与调用（会话召回），让 AI 既能跨会话积累经验，又能在单次对话中轻装前行。这恰是对“温故而知新，可以为师矣”的工程化复现：历史被结构化存储，关键信息被语义检索，上下文被动态压缩——每一次交互，都站在过往的阶梯上，望向更远的地方。
