Agent上下文管理：记忆、检索与Compaction完整指南

Agent 的上下文窗口既是工作内存，也是一个有限资源。

当前任务需要的文件、工具结果、历史决定和错误日志都想放进上下文，但上下文并不是越满越好。内容太少，Agent 会丢失关键背景；内容太多，重要信息会被噪声淹没，模型还可能把旧状态当成当前事实。

因此，记忆系统真正要解决的问题不是“让 Agent 记住一切”，而是让它在正确时间找到正确的信息，并知道这些信息是否过期、来自哪里、优先级是什么。

一、三种记忆不是一回事

工作记忆

当前上下文窗口中正在使用的信息，例如本轮任务目标、刚读取的文件、最近一次命令输出和等待确认的问题。

工作记忆速度快，但容量有限。任务结束或上下文压缩后，其中一部分可能被移出。

情节记忆

之前发生过的对话、工具调用、文件修改、测试失败、用户决定和任务事件。它回答“过去发生了什么”。

事件日志和会话记录属于这一层，但历史记录不等于已经理解的记忆，仍然需要检索和摘要。

语义或程序记忆

相对稳定的项目规则、用户偏好、领域知识、Skill、操作流程和长期决策。它回答“应该怎样做”。

三者混在一起，Agent 很容易把一次性的临时指令当成长期规则。设计记忆系统时，必须知道每条信息的类型、有效期和权威来源。

二、为什么文件不会自动成为记忆

把规则写进 AGENTS.md、项目文档或本地文件，只完成了持久化，不代表模型每次都会读取它。

从文件到可用记忆，至少还需要：

持久化文件
    |
检索或路径选择
    |
读取相关内容
    |
摘要、排序和去重
    |
注入当前上下文
    |
在任务中引用和验证

如果每次把整个项目文档都注入上下文，会增加噪声和成本；如果只加载一个简短摘要，又可能漏掉本次任务真正需要的限制。更合理的是分层加载：总规则、当前项目、当前任务和按需参考资料。

三、上下文注入要有优先级

可以把信息分成四层：

1. 安全和系统约束：权限、禁止事项和审批规则。
2. 当前任务：目标、输入、输出、完成条件和截止时间。
3. 项目状态：目录结构、当前版本、历史决定和已知问题。
4. 参考资料：文档、案例、旧日志和可选背景。

上下文不足时，优先保留前两层，再按任务需要加载项目和参考资料。不要为了“保险”把所有历史内容都放进去。

一个上下文选择器可以返回这样的信息：

{
  "path": "projects/blog.md",
  "reason": "当前任务涉及博客构建和发布",
  "updated_at": "2026-07-30T09:00:00+08:00",
  "priority": "high",
  "authority": "project-owner"
}

来源、更新时间、优先级和权威性会帮助 Agent 处理冲突。新鲜的当前项目状态，通常比几个月前的聊天记录更适合作为事实依据。

四、检索原语怎样工作

检索可以按关键词、路径、语义相似度、标签和时间过滤。个人项目不必一开始就搭建复杂向量数据库，先用清晰的目录、关键词搜索和索引文件，往往已经足够。

一个简单检索流程是：

读取任务关键词
    |
搜索文件名和正文
    |
按更新时间、项目和权限过滤
    |
读取匹配段落上下文
    |
去重并注入当前窗口

检索结果应该能告诉 Agent 为什么被选中。否则模型看到一段文档，却不知道它和当前任务的关系，仍然可能误用。

五、Compaction 不是简单截断历史

当上下文接近上限时，Harness 需要压缩历史，继续推进任务。最粗暴的方法是从开头删除一部分内容；更可靠的方法是把过去的工作转换成结构化摘要。

一个有用的 Compaction 摘要至少保留：

# 当前任务摘要

## 目标
要完成什么，完成条件是什么。

## 已完成
- 读取了哪些文件
- 执行了哪些命令
- 哪些检查已经通过

## 当前状态
- 正在处理哪一步
- 当前版本或分支
- 当前阻塞

## 关键决定
- 用户确认过什么
- 哪些方案被否决以及原因

## 失败记录
- 错误信息
- 已尝试方法
- 为什么没有继续重试

## 下一步
- 下一步动作
- 所需输入
- 完成后的验证方式

不要只摘要模型的回答，还要保留工具结果、用户决定和失败证据。否则恢复后的 Agent 可能重复执行已经失败的方案，或者重新询问用户已经回答过的问题。

六、工具输出要截断和卸载

日志、搜索结果、测试输出和网页正文可能非常大。完整输出直接进入上下文会迅速消耗预算。

更合理的策略是：

• 前几行保留启动信息；
• 最后几行保留错误和退出结果；
• 中间内容保存到文件；
• 向模型提供文件路径和摘要；
• 用户或 Agent 需要时再读取局部范围。

例如测试失败时，返回：

exit_code: 1
summary: 2 failed, 148 passed
stderr_path: artifacts/test-stderr.log
relevant_lines: 88-124, 301-336

这比把几万行日志全部粘进上下文更容易分析。截断必须告诉模型发生了截断，不能让它误以为看到的是完整输出。

七、Skills 和渐进式披露

Skill 适合保存程序记忆，但不应该每次把完整 Skill、所有参考资料和所有工具都加载进上下文。

渐进式披露可以分三层：

1. 描述层：Skill 解决什么问题、何时使用。
2. 指令层：任务真正匹配后加载执行步骤和输出规范。
3. 参考层：遇到具体分支时再读取样例、领域资料和长文档。

工具也可以按需加载。模型不需要在做文件分析时同时看到数据库迁移、浏览器自动化和云部署的全部工具定义。

八、会话恢复和分叉

持久化任务要支持恢复。恢复时不能只恢复最后一条消息，还要恢复：

• 任务目标和完成条件；
• 计划步骤和当前状态；
• 当前工作区版本；
• 已调用工具和关键结果；
• 用户审批记录；
• 预算、重试次数和阻塞原因。

分叉则适合尝试不同方案：保留共同上下文，在分支中选择另一种实现，再比较结果。分叉后的两个任务如果继续修改同一工作区，需要明确隔离目录或分支，否则结果会互相污染。

九、记忆写入要经过判断

让 Agent 自动更新记忆很方便，但不能把每句话都写入长期存储。至少要判断：

这是临时信息还是长期规则？
是否有明确来源？
是否只适用于当前项目？
是否可能包含敏感数据？
未来什么时候需要复核或过期？

可以为记忆记录增加元数据：来源、创建时间、最后验证时间、维护人、适用范围和失效条件。没有更新时间的规则，很容易在半年后仍然被当成事实。

十、上下文预算怎么分配

上下文预算不只是模型窗口大小，还包括工具定义、系统规则、任务输入、历史事件、检索资料和模型输出。

一个简单的优先级策略是：

安全约束 > 当前目标 > 当前状态 > 相关证据 > 旧历史 > 可选背景

预算不足时，先压缩旧历史和可选背景，不要删除完成条件、审批记录、失败证据和当前阻塞。工具输出也应按重要程度裁剪，而不是简单按字符从后面截断。

十一、记忆系统的常见失败

旧信息覆盖新信息

修复：保存时间、来源和版本，冲突时优先当前权威来源。

摘要丢失否决理由

修复：摘要中保留关键决定、被否决方案和原因。

文件存在但从未被读取

修复：建立索引、检索规则和注入记录。

上下文过度膨胀

修复：分层加载、工具输出卸载和渐进式披露。

敏感信息进入长期记忆

修复：写入前脱敏，使用 Secrets 系统保存真实凭证，不让模型把密钥写进项目文档。

结论

Agent 的记忆系统不是一个“大聊天记录”，而是工作记忆、情节记忆和程序记忆的组合。持久化只是第一步，真正让记忆有用的还有检索、优先级、上下文注入、摘要、压缩、版本和过期治理。

Compaction 的目标也不是让历史消失，而是把完成条件、当前状态、关键决定、失败证据和下一步动作保留下来，让任务可以跨上下文窗口继续。

参考资料

• Anthropic：Context Engineering for AI Agents，用于理解 Agent 上下文组织和信息选择。
• SQLite FTS5 文档，用于了解轻量级全文检索实现。