记忆压缩模式

记忆压缩模式

学习目标

读完本章后，你将能够：

• 理解记忆压缩的两个阶段：观察提取和会话摘要
• 设计结构化的 XML 输出格式用于 LLM 结构化输出
• 实现 token 经济学的成本感知压缩
• 处理 Agent 主动跳过摘要的边缘情况

核心概念

为什么需要记忆压缩

Agent 在单次会话中可能执行数十次工具调用，产生数千 token 的操作记录。如果不加处理地保存所有原始数据，会产生两个问题：

1. 存储膨胀：每次会话的完整转录文本可能达到数万 token
2. 注入成本：新会话启动时注入过多历史上下文，消耗大量输入 token

记忆压缩的核心思想是：用 AI 将大量原始操作记录提炼为少量结构化要点，既保留关键信息，又大幅降低存储和注入成本。

两阶段压缩管线

阶段 1：观察提取（Observation Extraction）

从每次工具使用的结果中，提取结构化的观察记录。每条观察包含：

字段	说明
type	观察类型（decision/bugfix/feature/refactor/change/discovery）
title	一句话标题
subtitle	补充说明
facts	关键事实列表
narrative	叙述性描述
concepts	涉及的概念标签
files_read	读取的文件
files_modified	修改的文件

阶段 2：会话摘要生成（Session Summarization）

在会话结束时（或达到触发条件时），AI 对整个会话进行总结，生成包含以下字段的摘要：

字段	说明
request	用户的请求
investigated	调查了什么
learned	学到了什么
completed	完成了什么
next_steps	后续步骤

结构化输出格式

LLM 使用 XML 格式输出压缩结果，便于正则解析：

<observation>
  <type>bugfix</type>
  <title>修复了认证中间件的 session 泄漏</title>
  <facts>
    <fact>根因是异步回调中未正确清理 session</fact>
    <fact>影响范围：所有并发请求</fact>
  </facts>
  <files_modified>
    <file>src/auth/middleware.ts</file>
  </files_modified>
</observation>

<summary>
  <request>修复用户报告的认证 bug</request>
  <investigated>auth middleware 的 session 生命周期管理</investigated>
  <learned>异步回调中的清理逻辑必须在 finally 块中执行</learned>
  <completed>修复了 session 泄漏问题</completed>
  <next_steps>添加集成测试覆盖该场景</next_steps>
</summary>

跳过机制

Agent 可以通过 <skip_summary reason="..."/> 标签主动跳过摘要生成。这用于以下场景：

• 会话中没有有意义的工作产出
• 用户仅执行了简单的查询操作
• Agent 判断压缩结果价值低

Token 经济学

压缩的收益可以通过 token 计数器量化：

• 发现成本：生成观察和摘要所消耗的 token（写入成本）
• 检索成本：注入上下文时的 token 消耗（读取成本）
• 压缩比：原始数据 token 数 / 压缩后 token 数

设计良好的压缩系统应该在写入成本和读取成本之间取得平衡：过度压缩导致信息丢失，压缩不足导致注入成本过高。

设计权衡

优势

• 信息密度高：每条观察仅包含关键事实，去除冗余
• 可检索：结构化字段支持按类型、文件、概念等维度过滤
• 可扩展：新增观察类型无需修改存储结构

代价

• 写入延迟：每次工具使用后需要等待 AI 生成观察
• 模型依赖：压缩质量依赖于所使用的 LLM 的理解能力
• 去重挑战：需要 content_hash 去重，避免重复记录相同的操作

替代方案

方案	优势	劣势
完整转录	无信息丢失	存储和注入成本极高
规则提取	快速、无模型成本	无法理解语义，遗漏关键信息
AI 压缩（本方案）	语义理解、信息密度高	模型依赖、写入延迟

参考来源

• Anthropic Claude API 文档
• ReAct: Synergizing Reasoning and Acting in Language Models

---

补充：Agno 的 MemoryManager 与 SummarizeStrategy

来源：Agno libs/agno/agno/memory/manager.py、libs/agno/agno/memory/strategies/summarize.py，2026-05-30

MemoryManager：独立模型管理记忆 CRUD

Agno 的 MemoryManager 是一个独立于 Agent 的组件，使用自己的模型（可与主 Agent 不同）管理用户记忆：

# 伪代码：MemoryManager 配置
manager = MemoryManager(
    model=OpenAIResponses(id="gpt-4o-mini"),  # 可以用更便宜的模型
    system_message="你是一个记忆管理助手...",
    memory_capture_instructions="提取关于用户的重要信息...",
)

提供 4 个工具给 Agent：

• add_memories：添加新记忆
• update_memories：更新已有记忆
• delete_memories：删除指定记忆
• clear_memories：清空所有记忆

SummarizeStrategy：记忆压缩策略

MemoryOptimizationStrategy 是抽象基类，SummarizeStrategy 是其实现：

SummarizeStrategy.optimize

def optimize(self, memories: List[UserMemory], model: Model) -> List[UserMemory]:
    # 将所有记忆合并为单一综合摘要
    system_prompt = "你是一个记忆压缩助手，将多条记忆合并为一条..."
    all_contents = [mem.memory for mem in memories]
    response = model.chat(messages=[
        Message(role="system", content=system_prompt),
        Message(role="user", content="\n".join(all_contents)),
    ])
    # 保留所有唯一 topic
    all_topics = list(set(t for mem in memories for t in mem.topics or []))
    return [UserMemory(memory=response.text, topics=all_topics)]

关键设计：

• 记忆 topic 去重合并，不丢失分类信息
• 检查 user_id 一致性，防止跨用户记忆泄漏
• 检查 agent_id / team_id 一致性（记录日志但不阻止）

后台线程启动

记忆创建作为后台线程（start_memory_future）启动，与主执行管线并行。主响应不等待记忆创建完成，在管线末尾（步骤 12）等待后台线程。这确保了记忆维护不增加用户感知延迟。