如何给Agent装上记忆并管好上下文：语义记忆、历史总结与Token预算的3套完整方案

本文基于开源项目engenharia-de-software-com-ia-aplicada（应用 AI 的软件工程课程仓库），面向新手拆解一套完整的Agent 记忆与上下文管理实践：包括语义记忆（remember / recall / forget）、历史总结（滚动摘要）和 Token 预算（ContextBuilder）三套可直接落地的方案，帮你快速让 LLM 助手“记住用户、装得下长对话、花得起 Token”。

🧠 为什么 Agent 需要记忆与上下文管理

大模型的上下文窗口有限，且默认“失忆”：昨天的对话今天不记得，用户说过的偏好每次都要重复。推荐系统其实早就在做类似的事——“记住”你的浏览偏好：

本项目在modulo04-criacao-de-agentes-autonomos-novo（自主 Agent 创建模块）中，用真实项目 OpsPilot 分两步解决：

三者层层叠加：先选内容（记忆召回 + 摘要），再控大小（预算裁剪），最后还要会测量（Token 估算）。

方案一：语义记忆——让 Agent 记住“事实”而不只是聊天记录

语义记忆的核心思路：把“事实”转成向量存起来，查询时用语义相似度而非关键词匹配来召回。

📌 关键参数（写死在 memory-store.ts 中）：

• Dedup 阈值 0.92：新事实与已存事实相似度> 0.92时直接拒绝，避免同一事实换句话存两遍；
• Recall 阈值 0.3：召回结果相似度必须≥ 0.3才注入 prompt；
• Top-K = 3：每轮最多注入 3 条相关事实。

技术要点：

1. 使用本地模型all-MiniLM-L6-v2（@huggingface/transformers）生成 embedding，mean pooling + 归一化，实现见 embeddings.ts；
2. 向量以 BLOB 存入 SQLite 的memories表（id, user_id, fact, embedding, created_at），按userId严格隔离；
3. 每轮POST /chat前执行recall(userId, query)，把命中的事实注入 prompt。

最能说明价值的一点：即使查询语句与事实没有任何共同单词，只要语义相关就能被召回——这是纯关键词检索做不到的。完整的验收标准与边界用例（空输入、阈值取法等）都写在 specs/008-semantic-memory/spec.md 中。

方案二：历史总结——8 条窗口 + 滚动摘要

长对话的第二道坎是“历史太长”。方案是剪枝（pruning）+ 滚动摘要：

• Prompt 中只保留最近 8 条消息原文；
• 更早的内容压缩成约150 token 的摘要，只保留“决策、事实、待办”三类关键信息；
• 摘要持久化在conversation_summaries表，并用watermark（水位线）记录已覆盖到哪里；
• 绝不每轮重新生成：只有当又有 8 条新消息滑出窗口时才触发一次总结，并与旧摘要**合并（merge）**后落库。

这套设计的精妙之处在于成本控制：fake 测试会断言“不满 8 条滑出时总结器调用 0 次，满 8 条时恰好 1 次”；总结器失败也不会打断对话（fail-safe），watermark 只在持久化成功后前进。相关规格文档：specs/011-history-summarization/spec.md。

方案三：Token 预算——ContextBuilder 的“分区限额”

内容选出来之后，最后一道闸门是按分区设 Token 上限。context-builder.ts 是所有策略（ReAct、reflect、plan-execute 等）唯一的 prompt 组装入口，默认预算如下（可用环境变量覆盖）：

裁剪顺序是确定性的、可测试的：历史按时间从旧到新淘汰，记忆按 score 从低到高淘汰，同分用稳定次序平局——这让“低预算下到底切了什么”可以精确断言。规格与边界用例见 specs/012-context-builder-budget/spec.md。

📏 地基能力：先学会测量 Token

三套方案都依赖同一把“尺子”（tokens.ts）：

• 估算：estimateTokens = floor(chars / 4)，快速且确定；
• 实测：解析 LLM 返回的 usage 拿到真实promptTokens；
• /chat的响应里带上metrics.promptTokens与按来源拆分的contextBreakdown（system / history / memories / message），每轮都能直观看到上下文涨了多少。

细节见 specs/010-context-measurement/spec.md。

🚀 快速上手：跑一遍 30 轮长对话演示

在 05-gerenciamento-de-contextos 目录下，按官方步骤：

1. npm ci && cp .env.example .env
2. npm run dev启动服务
3. ./scripts/conversa-longa.sh——自动跑 30 轮对话，终端会逐轮打印promptTokens，你能亲眼看到：摘要事件summarize触发、contextBreakdown稳定、且早期决策（如“暂停部署”）在摘要化之后依然能被找回；
4. npm test && npm run typecheck验证全部确定性测试通过。

记忆部分同理，见 04-memoria-e-reflexao-em-agentes-autonomos/UNIDADE.md。

📚 关键文件清单

✅ 小结

给 Agent 装上可靠的记忆，本质是三个工程问题：

1. 记什么——语义记忆用 embedding 去重（0.92）+ 相似度召回（top-3、≥0.3），按用户隔离；
2. 留多少——8 条原文窗口 + 150 token 滚动摘要，只在“滑出 8 条”时增量合并，持久化可审计；
3. 花多少——ContextBuilder 单一入口按分区预算裁剪，system 与当前消息永不牺牲，所有规则确定可测。

照 05-gerenciamento-de-contextos/UNIDADE.md 的步骤跑一次conversa-longa.sh，你就能在自己的项目里复现这套“装得下、记得住、算得清”的上下文管理方案。