Memory System - 跨会话认知积累

Memory vs Context Compact#

很多人混淆 Memory 和 Context Compact：

核心区别：

• Memory：解决持久化问题——会话结束后仍保留。
• Context Compact：解决临时容量问题——会话内上下文爆炸。

位置差异：

• Memory 在 System prompt 中，每轮新建，不被 Compact 影响。
• Context Compact 在 Messages[] 中，压缩 tool_result。

设计张力：持久化问题用 Memory，临时容量问题用 Compact。两套机制各有边界，互不干扰。

验证你的理解#

Q1：Context Compact 会压缩 Memory 吗？为什么？

:::details 答案 不会。Memory 在 System prompt 中，不在 Messages[]。

Context Compact 只压缩 Messages[] 中的 tool_result——替换为占位符或生成摘要。

System prompt 每轮新建——build_system_prompt() 重新生成 memory_section，注入 System prompt。System prompt 不累积追加，不会被 Compact。

设计理由：Memory 是持久化认知积累，应该每轮可见。如果放在 Messages[]，会被 Compact 压缩，导致模型看不到历史记忆。 :::

四种类型定义#

关键点：user 是个人偏好，project 是团队约定。不要混淆。

案例对比：

不存清单：能从代码看出来就不存#

不是所有信息都该存 Memory。有明确边界：

核心原则：能从代码直接看出来就不存。

反例分析：

四类型判断流程#

验证你的理解#

Q2：用户说”记住 src/auth.py 是认证模块入口”，应该存吗？

:::details 答案 不应该存。

理由：

1. 文件路径可从代码直接看出（看 import 关系）——能从代码看出来就不存。
2. 如果文件改名，Memory 会过时——造成漂移风险。
3. Reference 类型是外部资源指针（看板 URL），不是代码内部路径。

正确处理：不存 Memory。模型每次从代码 import 关系推断认证模块位置。

如果存的是”认证模块设计原因是支持多租户”，应该存——代码看不出设计原因，存决策追溯有价值。 :::

save_memory 流程#

1
def save_memory(name: str, content: str, type_: str) -> str:
2
    # 1. 写文件
3
    path = MEMORY_DIR / f"{name}.md"
4
    frontmatter = f"---\nname: {name}\ntype: {type_}\n---\n"
5
    path.write_text(frontmatter + content)
6

7
    # 2. 更新字典
8
    memories[name] = {"type": type_, "content": content}
9

10
    # 3. 重建索引
11
    rebuild_index()
12

13
    return f"Memory '{name}' saved."

三步同步：

关键点：save_memory 返回前已完成三件事——下一轮 build_system_prompt 直接从字典读取。

Memory 注入流程#

流程说明：

• 会话初始化：load_all 扫描 .memory 目录，填充 memories 字典。
• Agent Loop：build_system_prompt 从字典读取，生成 memory_section，注入 System prompt。
• 保存 Memory：save_memory 写文件 + 更新字典 + 重建索引——下一轮 Loop 可见。

验证你的理解#

Q3：save_memory 调用后，Memory 什么时候被模型看到？

:::details 答案 下一轮 build_system_prompt 时看到。

同步更新机制：save_memory 返回前已完成三件事：

1. 写文件（持久化）
2. 更新 memories 字典（缓存）
3. 重建索引（刷新 MEMORY.md）

下一轮 agent_loop 入口，build_system_prompt 从 memories 字典读取——直接看到新 Memory，不需要重新加载文件。

不是异步加载——save_memory 立刻更新缓存，下一轮可见。 :::

漂移本质#

漂移风险：Memory 记录的文件路径、模块结构可能过时——文件改名、重构后 Memory 失效。

案例：

1
Memory: "认证模块在 src/auth.py"
2
实际状态: 文件已迁移到 src/core/auth.py
3
结果: Memory 过时，模型按旧路径查找会失败

漂移处理流程#

处理原则：

• 方向提示：Memory 给方向，不当作绝对答案。
• 验证当前状态：使用 Memory 前读当前文件/配置。
• 冲突优先相信代码：Memory vs 当前状态不一致，优先相信代码。

为什么优先相信代码？

代码是真实状态——文件改名后 Memory 过时，但代码路径是当前正确的。Memory 是历史快照，代码是实时状态。

验证你的理解#

Q4：Memory 说”认证模块在 src/auth.py”，但实际文件已迁移到 src/core/auth.py，怎么处理？

:::details 答案 优先相信当前代码状态。

处理步骤：

1. Memory 给方向提示——“认证模块存在”
2. 读当前代码结构——发现文件在 src/core/auth.py
3. Memory vs 当前状态冲突——路径不一致
4. 优先相信当前状态——使用 src/core/auth.py
5. 给用户结论时再验证一次——确认认证模块确实在新位置

不建议更新 Memory——文件路径可从代码看出，不该存 Memory。正确的 Memory 应存”认证模块设计原因”，不是路径。 :::

7 Gates 检查#

Dream Consolidator 触发前，先过 7 Gates：

Gate 分类：

4 Phases 执行#

通过 7 Gates 后，执行 4 Phases：

Phase 4 200 行限制：

MEMORY.md 索引限制 200 行——给人阅读定位，不限制注入量。

load_memory_prompt() 加载所有 Memory 文件，不受索引截断限制。真正限制注入量的是 Dream Consolidator 整合机制。

Dream Consolidator 流程#

设计理由：

• Gate 6 为什么需要 ≥5 sessions？数据积累不够——清理太早会丢失有价值 Memory。等待更多会话，更准确判断哪些 Memory 真正过期。
• Gate 模式迁移：后台任务防护——前置条件 + 频率限制 + 并发保护。可用于其他后台清理机制（如数据库日志清理）。

验证你的理解#

Q5：Gate 6 为什么需要 ≥5 sessions 才触发 Dream Consolidator？

:::details 答案 数据积累不够——清理太早会误删有价值 Memory。

理由：

1. 少于 5 次会话——Memory 数量少，判断”过期”的依据不足
2. 等待更多会话——更准确判断哪些 Memory 真正被频繁使用，哪些确实过期
3. 防止过度清理——Dream Consolidator 是删除机制，误删代价高

Gate 模式迁移：后台任务防护——前置条件（G1-3）+ 频率控制（G4-6）+ 并发安全（G7）。可用于其他后台清理机制（如数据库日志清理、缓存过期检查）。 :::

与后续课程的关系#

理解 L09 后，你会发现后续课程都在 Memory System 上叠加——循环本身始终不变：

核心洞察：Memory System 是”跨会话认知积累”的机制。理解 L09，就理解了 Agent 如何”持久化有价值信息不丢失”。后续课程都在扩展 Memory——System Prompt 设计、后台任务清理。

L09 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

用户说”团队约定所有 commit 必须带 ticket ID，否则 CI 会失败”，应该存 Memory 吗？存什么类型？

:::details L2 层级回答 应该存 Memory，类型是 project。

分析：

1. 判断是否存 Memory：团队约定不能从代码直接看出——代码看不出”为什么必须带 ticket ID”，存决策追溯有价值。
2. 判断类型：不是个人偏好（user），不是用户纠正（feedback），不是外部资源（reference）——是团队约定，属于 project 类型。
3. 存储内容：“commit 必须带 ticket ID，否则 CI 会失败”——约定 + 原因。不存”commit 规范”，那是 Task/Plan，会过期。

注意边界：

• 如果存”commit 规范模板”，不该存 Memory——那是临时任务规则，会过期。
• 如果存”CI 配置文件路径”，不该存 Memory——文件路径可从代码看出，存了会有漂移风险。 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L09，不只是记住四种类型，而是掌握”如何判断什么该存什么不该存”的设计原则。

Memory 生命周期#

四类型判断流程#

漂移处理流程#

Dream Consolidator 流程#

Memory vs Context Compact#