跳转至

Agent Memory 与评测方法探索实习设计

分支文档快照 · 同步于 2026-09-09 · 来源：origin/summer-intern @ 9f4cdc5 · 原路径：docs/superpowers/specs/2026-07-10-agent-memory-evaluation-internship-design.md。正文描述的是该分支的方案或进展，合入与验收状态以当前看板为准。

日期：2026-07-10
验证平台：sqlopt-skills 现有 SQL 优化流水线
周期：8 周，每人每周约 2 天，单人约 16 人天

1. 目标与定位

本实习项目的首要目标不是承诺 SQL 优化率从 20% 提升到 50%，而是形成可迁移到其他工具调用型 Agent 的 Memory 方法和评测方法。sqlopt-skills 是统一的验证平台，用于检验方法是否可操作、可复现及边界是否清晰。

目标按以下顺序排列：

  1. 沉淀通用的 Agent Memory 方法，包括分类、生命周期、选型依据、隔离和污染治理。
  2. 沉淀通用的 Agent 评测方法，包括数据集设计、指标体系、对照实验、失败归因和可信度规则。
  3. 在当前 SQL 优化流水线上实现最小原型和可复现实验，验证上述方法。
  4. 观察 SQL 优化效果并分析原因，但不将预设提升幅度作为结项门槛。

2. 与现有项目的对应关系

2.1 高度对应的项目能力

研究对象 当前项目落点 可研究问题
工作记忆与任务状态 agent-workspace/ws_xxx/cases/{case}/round_N/ 跨轮次保留什么状态，如何压缩和恢复
数据库上下文 table_ctx_cache/ 及 table_ctx.py 全量加载、裁剪、按需加载的成本与信息损失
结果记忆 results/*_result.json 哪些成功或失败经验值得长期保存
记忆注入点 SQL 分析、生成、复核等 skills 在哪个阶段注入哪类记忆，如何防止干扰
评测数据流 collect_results.py、export 脚本、历史 fixtures 如何从运行记录形成可追溯的评测证据
回归测试 test_write_result_status.py、test_e2e_export.py 如何扩展为策略对照、消融和稳定性测试
历史样本 files/0625/、files/0626/ 数据库受限时如何开展离线复现和抽样验证

2.2 原任务说明中的偏差

原说明的研究方向与项目相关，但部分任务把验证平台扩张成了新的 Agent 或评测产品，超出单人 16 人天的合理范围：

  • 独立搭建 LangGraph Agent 会产生第二套运行架构，削弱与现有 skills 的直接对应关系。
  • 完整 SQLite CRUD、历史查询和可视化平台属于产品工程，不是方法论验证的必要条件。
  • 强制构造 60 条测试 SQL并完成 200 条标注，在数据库环境受限时容易牺牲标注质量。
  • 同时实现 LangGraph、CrewAI、AutoGen 或复杂 Multi-Agent 编排，范围过大且不能直接回答 Memory 核心问题。
  • 预设 Memory 对优化率贡献 +8%~12% 缺少实验依据，不应作为实习生验收承诺。

因此，成熟框架只用于技术调研和选型对照；工程实现统一落在当前流水线，以最小原型证明通用方法。

3. 组织方式

采用“主责 + 交叉验收”：

  • 实习生 A 主责 Memory 方法研究和原型。
  • 实习生 B 主责评测方法、数据和实验协议。
  • 两人在第 2 周共同冻结实验协议；第 4 周开始合流；第 5 至第 7 周互相提供接口、数据和复核。

这种方式既保留各方向的研究深度，又避免 Memory 原型完成后才发现无法客观评测。

4. 实习生 A：Memory 通用方法探索

4.1 核心研究问题

  1. Agent 应记住哪些信息，哪些信息不应进入长期记忆？
  2. 记忆应在何时写入、召回、注入、更新和失效？
  3. 如何在上下文质量、token 成本和干扰风险之间取舍？
  4. 如何隔离数据库、租户、任务类型和版本，避免跨域污染？
  5. 文件缓存、结构化检索、向量检索和框架 Checkpointer 分别适合什么场景？

4.2 P0 任务

  1. 盘点当前流水线的显式与隐式 Memory，画出从输入、上下文、case/round 到结果的生命周期。
  2. 调研 LangGraph Checkpointer、Mem0/MemGPT、RAG 等机制，产出面向工具调用型 Agent 的选型矩阵；不搭建独立 LangGraph Agent。
  3. 建立通用 Memory taxonomy，至少覆盖：
  4. 工作记忆：当前任务状态和中间步骤；
  5. 语义记忆：稳定事实、规则和领域知识；
  6. 情景记忆：过去任务、决策、结果和失败；
  7. 工具/过程记忆：工具调用条件、参数和执行反馈。
  8. 定义经验条目 schema，至少包含作用域、来源、证据、适用条件、置信度、版本、创建时间和失效条件。
  9. 实现上下文策略最小原型，对比当前基线与按 SQL 依赖加载策略。
  10. 实现轻量经验召回与注入原型。优先采用结构化过滤加文本相似度；只有证据表明需要时才引入向量库。
  11. 完成有/无 Memory、不同上下文策略的消融实验，记录正例、反例、误召回和污染案例。
  12. 输出《Agent Memory 通用方法论》和 SQL 场景参考实现说明。

4.3 P1 任务

  • 研究不同 skill 阶段的记忆注入策略。
  • 研究多角色 Agent 的 Memory 共享和隔离，但只形成设计建议，不要求实现 Multi-Agent 系统。

5. 实习生 B：Agent 评测通用方法探索

5.1 核心研究问题

  1. 应如何把 Agent 的过程、结果、成本和稳定性转化为可计算指标？
  2. 数据库真实执行受限时，哪些结论可以由离线证据支持，哪些不能外推？
  3. 如何设计公平的基线、对照、消融、重复运行和抽样人工复核？
  4. 如何区分模型失败、上下文失败、Memory 失败、工具失败和评测器失败？
  5. LLM-as-Judge 在 SQL 等价性和优化质量判断中只能承担什么辅助角色？

5.2 P0 任务

  1. 盘点现有历史样本、结果 schema、状态机、单测和 E2E 测试，列出可用证据与缺口。
  2. 调研工具调用型 Agent 和 SQL Agent 的评测方法，明确规则判定、真实执行、人工复核和 LLM-as-Judge 的证据等级。
  3. 定义通用 run schema，至少记录样本版本、模型版本、提示版本、策略配置、随机参数、输入、输出、指标、失败标签和证据来源。
  4. 建立数据集分层方法：
  5. 核心集：20 至 30 条代表性历史样本，用于快速实验；
  6. 回归集：覆盖主要 SQL 类型、集中式/分布式模式和已知失败；
  7. 挑战集：长上下文、相似但不可复用经验、冲突经验等 Memory 风险场景。
  8. 扩展轻量评测 runner，使策略批量运行、单样本复现和结果追溯成为可能；不建设完整 CRUD 或可视化平台。
  9. 建立失败归因 taxonomy，并对 Memory 实验的失败样本完成人工复核。
  10. 设计并执行消融、重复运行和稳定性实验；数据库可用时进行少量真实执行抽样校验。
  11. 输出《Agent 评测通用方法论》、数据说明和复现指南。

5.3 P1 任务

  • 研究 LLM-as-Judge 与人工复核的一致性，只将其作为辅助指标。
  • 在样本允许时分析集中式与分布式数据库的差异，不强制建设跨库平台。

6. 共同实验协议

第 2 周结束前，两人共同固定以下接口：

6.1 Memory 策略输出

  • strategy_id 与版本；
  • 策略配置；
  • 候选记忆输入；
  • 召回结果与分数；
  • 最终注入内容；
  • 过滤或拒绝原因；
  • 与单次运行关联的 run_id。

6.2 评测运行记录

  • 样本、模型、提示和代码版本；
  • 策略配置和随机参数；
  • 原始输入、Memory 输入和 Agent 输出；
  • 规则指标、人工判定和可用的真实执行结果；
  • 失败标签、判定依据与证据等级。

任一结论必须能够从汇总报告追溯到单次运行的输入、策略、输出和判定依据。数据库不可用时，结论必须标注为离线证据，不得表述为线上性能结论。

7. 指标体系

7.1 Memory 主指标

  • 召回命中率或 Precision@K；
  • 关键上下文信息覆盖率；
  • 无关上下文比例；
  • 输入 token 数及相对节省；
  • 记忆污染率；
  • 跨任务复用成功率；
  • 因错误记忆导致的结果退化率。

7.2 评测方法主指标

  • 用例分类覆盖率；
  • 指标可计算率；
  • 重复运行一致性；
  • 失败可归因率；
  • 自动判定与人工复核一致性；
  • 从报告到原始证据的可追溯率；
  • 按复现指南成功复跑的比例。

7.3 SQL 平台验证指标

  • 结果等价性通过率；
  • 有效优化建议率；
  • 状态判定正确率；
  • 真实数据库可用时的耗时改善；
  • 集中式和分布式场景的失败差异。

SQL 指标用于验证方法，不设预定提升幅度。无显著提升但能解释适用边界、失败机制和改进条件，同样是有效研究结论。

8. 八周安排

周次 Memory 主责 评测主责 共同里程碑
W1 盘点 Memory 流和上下文链路 盘点测试资产和证据能力 现状与问题清单
W2 框架/机制调研及选型矩阵 评测方法和证据等级调研 冻结实验协议、基线和样本划分
W3 taxonomy、生命周期和经验 schema 用例分层、失败 taxonomy、核心集 schema 与核心集评审
W4 上下文基线与按需加载原型 runner 和运行记录扩展 首轮上下文消融实验
W5 轻量经验召回与注入原型 版本化结果与失败归因 有/无 Memory A/B v1
W6 污染、隔离、失效策略分析 回归集复核与抽样真实验证 中期结论及风险清单
W7 根据证据迭代，按进度开展 P1 稳定性复跑与人工抽检 最终消融、失败案例集
W8 Memory 方法论与参考实现说明 评测方法论与复现指南 联合总结及迁移路线图

9. 交付物与验收

编号 交付物 主验收标准
D1 Agent Memory 通用方法论 分类完整；生命周期和选型条件明确；包含污染、隔离、更新和遗忘规则
D2 Memory 最小参考实现 能在现有流水线运行；配置和输入输出可追溯；至少包含一个上下文策略和一个经验召回策略
D3 Agent 评测通用方法论 覆盖数据、指标、对照、消融、稳定性、证据等级和失败归因
D4 评测协议、schema 与轻量 runner 支持批量实验和单样本复现；不依赖完整平台；运行记录可追溯
D5 Memory 消融实验报告 使用冻结的协议；同时报告正例、反例、退化和边界；区分离线与真实执行证据
D6 联合迁移总结 说明哪些方法可迁移到代码、运维或其他工具调用型 Agent，以及迁移前提

共同质量门槛：

  • 调研结论有来源、有比较维度、有适用边界，不是资料罗列。
  • 实验包含公平基线、固定数据版本、明确变量和可复现步骤。
  • 失败实验必须保留并解释，不只汇报正向结果。
  • 原型追求最小可验证，不追求生产级完整度。

10. 范围控制与风险降级

明确不纳入 P0：

  • 独立 LangGraph Agent；
  • CrewAI、AutoGen 或完整 Multi-Agent 实现；
  • 完整 SQLite CRUD、Web UI 或可视化平台；
  • 强制完成 60 条新 SQL 和 200 条标注；
  • 生产级向量数据库和大规模在线评测；
  • 预先承诺固定优化率提升。

进度受限时按以下顺序降级：

  1. 取消 Skill 模式切换实验；
  2. 取消向量数据库，保留结构化检索和文本相似度；
  3. 缩小 SQL 回归集但保留核心集和挑战集；
  4. 将真实数据库验证缩减为抽样或后续计划。

不得降级的内容：通用方法文档、统一实验协议、对照/消融、失败归因和复现说明。

11. 成功判定

本实习成功不等同于 SQL 优化率显著提升。满足以下条件即可视为达到核心目标：

  1. 两套方法论能够被当前项目以外的工具调用型 Agent 理解和复用。
  2. 方法在 SQL 优化验证平台上有可运行的最小实例和可追溯证据。
  3. 实验能够说明方法何时有效、何时无效以及为什么。
  4. 第三方可以依据文档复现核心实验。
  5. SQL 优化效果无论正向、无显著变化或出现退化，都被准确记录并形成下一步决策依据。