Agent做不好别急着加记忆：先查五层瓶颈再决定

一个 Agent 做错了事，团队很容易给出同一个解释：它忘了，所以应该加长期记忆、向量库或知识图谱。这个解释有时成立，但经常把问题带偏。目标没有写清楚、项目资料拿不到、工具不能验证、失败反馈没有回流，甚至使用者自己说不清“什么算做好”，都可能让 Agent 看起来像失忆。

最近一段关于 Agent 工程的演讲被二次传播成“Prompt 已经不重要，真正需要 Graph Engineering”。但根据用户提供的完整视频整理和时间戳，讲者讨论的并不是某一种数据库，也没有承诺 Agent 可以永远记住一切。他关心的是人和 Agent 如何互相理解，以及模型能力怎样通过上下文、工具和反馈被释放出来。

本文把这段材料整理成一个排查框架：遇到 Agent 做不好时，先检查目标、上下文、工具、反馈和人的判断，再判断记忆是否是需要投入的那一层。五层框架是本文的编辑整理，不是演讲中逐字给出的原始框架。

1. 先把“记忆问题”拆开

“它忘了”至少可能对应四种不同现象：

它从来没有拿到过这份信息。
它拿到过，但信息没有被放在当前任务需要的位置。
它知道信息在哪里，却没有搜索或读取的工具。
它做过正确判断，但后续没有保存任务状态。
它知道规则，却不知道最后结果应该长什么样。

这几种现象的修复方向完全不同。

所以，记忆不是 Agent 系统里的总开关。它只是保存和取回信息的一种机制。

2. 第一层：目标能不能验收

很多 Agent 任务从一句模糊要求开始：

帮我把这个项目优化一下。
帮我把视频做得更专业。
解释一下认证模块。

这些话对人类同事也不够具体。Agent 可能会把“优化”理解成重构代码，把“专业”理解成加特效，把“解释”理解成逐文件摘要。结果看起来很努力，但未必解决了真实问题。

先把目标改成可以检查的形式：

目标：让新加入项目的后端开发者在 10 分钟内理解登录请求的完整路径。
范围：只分析 auth module 及其直接调用方，不修改代码。
输出：入口文件、调用链、鉴权边界、失败分支和仍需确认的问题。
验收：每个结论都能回到文件路径或测试；不确定内容单独列出。

目标清楚以后，Agent 即使没有长期记忆，也可能完成一次合格任务。目标不清楚时，新增记忆只会让它更有把握地执行错误方向。

目标层的检查问题

开始加记忆前，先回答：

1. 最终产物是什么，是代码、报告、解释还是决策建议？
2. 哪些结果可以通过测试、文件、截图或数据核对？
3. 哪些地方必须由人判断，不能交给模型自行决定？
4. 哪些文件、模块或业务范围明确不在本次任务内？

如果这四个问题回答不出来，先补任务书，不要先建记忆库。

3. 第二层：上下文能不能自己找到

上下文不是“把所有知道的内容都放进 Prompt”。它更像一次有预算的取材过程：Agent 需要知道哪些背景，哪些内容现在必须读，哪些内容应该等到需要时再找。

例如“解释 auth module”这句话至少缺少以下信息：

提问者懂不懂 TypeScript？
项目规模有多大？
提问者是要接手维护、做代码评审，还是理解业务流程？
认证逻辑是否还分散在配置、数据库和历史文档中？
当前分支和生产版本是否一致？

同一句话面对不同的人和项目，合适的回答会完全不同。记忆可以补充用户偏好或长期项目事实，但不能替代对当前仓库、当前分支和当前目标的调查。

更稳的做法是让 Agent 先建立查找路径：

先不要回答结论。
请先确认 auth module 的入口文件、直接调用方、相关配置和测试。
如果信息分散，请列出你准备搜索的路径。
只读取与认证流程直接相关的文件，遇到不确定命名再扩大范围。

这样做的重点不是让模型记住更多，而是让模型知道去哪里找。

Anthropic 的 Effective context engineering for AI agents 将上下文工程描述为对模型上下文进行设计、组织和管理的工作。这个概念的核心不是“上下文越长越好”，而是让当前任务获得足够且相关的信息。具体项目的实现方式会随工具和版本变化，不能把一篇工程文章直接当成所有 Agent 的固定架构。

4. 第三层：工具能不能把能力释放出来

模型可能具备搜索、计算、执行和检查的潜力，但如果环境只提供一个聊天输入框，这些能力就未必能表现出来。

以代码任务为例，单纯要求模型“从记忆中找出所有符合条件的名称”，和允许它下载完整数据、执行筛选、查看结果，是两种完全不同的任务设置。前者考验封闭上下文中的回忆，后者增加了信息获取和结果核对的路径。

因此，Agent 失败时要检查：

它能否读取相关文件？
它能否搜索目录、日志或文档？
它能否执行必要的计算或测试？
它能否看到执行结果？
它能否在失败后重新选择路径？
它有没有权限把结果写到正确位置？

如果答案大多是否定的，继续优化 Prompt 的收益通常有限。应该先补工具、补权限或缩小任务范围。

工具也不是越多越好。工具接口过于细碎、参数含义不清或返回信息噪声很大，反而会增加模型的决策负担。工具设计需要和当前模型的行动方式一起复查：以前必须由人点击的步骤，模型变强后可能可以直接搜索；以前只能填写一次表单的工具，可能已经需要支持连续访谈或结构化报告。

5. 第四层：反馈有没有回到循环

一次执行结束才告诉 Agent“结果不对”，反馈已经太晚了。更有效的循环是：

提出假设
  -> 执行一个可观察动作
  -> 读取结果
  -> 与验收条件比较
  -> 记录失败原因
  -> 调整下一步

对代码任务来说，反馈可以是测试输出、类型检查、diff、截图和运行日志。对文档任务来说，反馈可以是来源标注、字段核对、受众审阅和格式检查。对视频任务来说，反馈可能是画面、音频、色彩和节奏的对照样例。

如果 Agent 每次失败都重新开始，它确实会像忘记了过去。但这不是长期记忆一定缺失，也可能只是没有任务状态文件。

一个最小状态记录可以这样写：

# Task State

## Goal
解释认证模块的登录和刷新流程。

## Done
- 找到登录入口和 token 刷新函数。
- 确认失败重试只发生在请求层。

## Failed attempts
- 只读 auth/index.ts 无法解释权限判断。

## Evidence
- src/auth/index.ts
- src/middleware/require-user.ts
- tests/auth/refresh.test.ts

## Next
检查权限中间件和刷新失败测试。

## Needs human decision
是否需要覆盖旧版客户端的兼容分支。

这个文件保存的是当前任务的状态，不是所有历史对话。它的价值在于让下一轮知道已经做过什么、为什么失败、下一步做什么。

6. 第五层：人能不能说清什么算好

这是最容易被忽视的一层。

如果使用者自己不知道“专业的视频应该是什么颜色”“这份报告面向谁”“认证解释要深入到哪一步”，Agent 就只能把一个模糊目标做得更完整。它可以生成更多文字、更多组件和更多版本，但不能替人凭空创造验收标准。

用户提供的演讲整理中，讲者用视频生产过程说明了这一点：第一版做出来以后，他发现颜色不对，但一开始并不熟悉色彩分级，也说不清哪里不对。于是他先让 Agent 解释色彩分级、补充可视化，再把新概念和自己熟悉的 shader 联系起来。人的心智模型变清楚以后，提示和验收才有了改进方向。

这个案例只能说明一种协作过程，不能单独证明成片质量，也不能推出 Agent 在视频制作上普遍可靠。它的启发在于：当人无法描述偏差时，先学习和探索，往往比继续堆背景资料更重要。

7. 记忆到底应该保存什么

经过前面五层排查，确认问题确实需要跨任务保留信息时，记忆才值得进入设计。

比较适合保存的内容包括：

不适合直接长期保存的内容包括：

未经核对的模型推测。
已经失效的临时路径。
没有来源的结论。
带有敏感信息的原始对话。
只适用于一次任务的局部猜测。

把所有历史对话压缩后放进一个向量库，并不会自动得到好记忆。真正要设计的是：什么值得记、什么时候召回、召回后如何标注来源、旧信息如何失效，以及冲突时由谁决定。

8. 让 Agent 按需取上下文

Anthropic 的 Equipping agents for the real world with Agent Skills 讨论了将专业能力组织成可逐步发现和加载的技能。这里能借鉴的是“渐进披露”思路：先给 Agent 一个清晰的入口和索引，需要时再读取具体文件，而不是把所有细节一次性塞进上下文。

在自己的项目里，可以先用很朴素的目录和规则实现：

project/
  AGENTS.md          # 长期规则和验证命令
  docs/index.md      # 资料索引
  tasks/current.md   # 当前任务状态
  skills/             # 可复用流程说明
  src/

Agent 第一次只读取规则和索引；当任务涉及认证时，再沿索引读取认证文档、源代码和测试。这样做不要求任何特定数据库，也不保证所有任务都能自动找到正确资料，但比把整个项目历史全部注入更容易检查。

9. 一套实际排查顺序

遇到 Agent 结果不好，可以按下面的顺序做一次小型诊断：

第一步：复述验收条件

让 Agent 先写出“完成意味着什么”。如果它和人的理解不同，先修目标。

第二步：列出证据路径

要求它列出会读取哪些文件、数据或工具结果。路径不对，说明上下文获取有问题。

第三步：给一个最小工具

不要一口气接十个工具。先给搜索、读取或测试中的一个，观察错误是否转化为可检查的动作。

第四步：记录失败而不是重复重试

每次失败写原因、尝试动作和新证据。相同输入和相同工具连续重试，通常只会重复同一种失败。

第五步：让人补一个可观察样例

给出一份“好结果”和一份“不能接受的结果”，或者说明一个具体反例。Agent 有了对照，反馈才更具体。

第六步：最后再判断是否需要记忆

只有当任务确实跨多个会话或多个阶段，而且信息稳定、可验证、值得复用，才增加记忆或检查点。

10. 结论与限制

Agent 做不好时，记忆可能是答案，但不是默认答案。先查目标，再查上下文获取；接着查工具和反馈，最后检查人是否能定义质量标准。五层中任何一层缺失，都可能让模型表现得像“忘了”。

本文的五层框架是对用户提供的演讲材料和 Anthropic 官方工程文章的编辑归纳，不是讲者在视频中给出的正式分类。官方页面讨论的是具体工程方向，不能替代你对当前工具版本、项目权限和任务数据的验证。

下一次遇到 Agent 失败，可以先保留一次失败记录：任务目标、可用资料、工具列表、执行轨迹、验证结果和人工判断。证据齐全以后，再决定是改 Prompt、补工具、加检查点，还是增加长期记忆。这样做的成本通常低于一开始就把整个历史系统复杂化。

资料与说明

• 演讲材料：用户提供的《Seeing like an Agent》视频信息、时间戳整理和转录。视频案例在本文中均标注为“视频展示”或“据转录整理”，不作为统一性能基准。
• Anthropic：Effective context engineering for AI agents：用于支撑上下文选择、组织和管理的工程背景。
• Anthropic：Equipping agents for the real world with Agent Skills：用于支撑技能组织和渐进披露的背景。