1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”“hindsight”这个词本身很有意思字面意思是“事后的洞察力”中文常翻译成“后见之明”。放在LLM Agent的语境里它指向一个非常具体且要命的问题Agent在完成一轮任务之后能不能回头看看自己刚才做了什么、哪些做对了、哪些做错了并且把这份“回头看”的结论沉淀下来变成下一次行动的参考这个问题听起来简单但真正动手搭过Agent的人都知道绝大多数Agent是“金鱼记忆”——上下文窗口一关上一轮的经验就归零了。你让它帮你订机票它订错了日期你纠正它它道歉然后下一轮同样的任务它可能再错一遍。这不是模型不够聪明而是记忆架构里缺少一个“事后复盘”的环节。我最初接触这个方向是因为在做一个多步骤任务编排的Agent时发现它在第3步犯的错到第7步还在重复。排查下来根因不是prompt写得不好而是Agent的working memory里只有“当前状态”没有“历史决策的因果链”。换句话说它知道自己现在在哪但不知道自己是怎么走到这儿的更不知道之前哪一步走岔了。“hindsight”要解决的就是这件事。它不是一个具体的开源项目名而是一类Agent记忆架构的设计模式在Agent完成一个episode之后触发一个复盘机制把执行轨迹trajectory压缩成结构化的经验条目写入长期记忆并在后续任务中通过检索把这些经验注入到决策上下文中。配合MCP协议做工具调用、Docker做环境隔离这套东西可以跑得相当稳。这篇文章适合谁看如果你正在搭Agent、调Agent、被Agent的“重复犯错”折磨过或者你听说过agent memory、MCP、LLM wiki这些词但还没串起来那接下来的内容应该能帮你省不少试错时间。我会从架构设计讲到实操落地包括Docker环境怎么配、MCP server怎么接、记忆条目怎么设计、检索怎么调参以及我踩过的那些坑。2. 核心架构拆解hindsight模式到底怎么运转2.1 三个记忆层working memory、episodic memory、semantic memory在hindsight模式里Agent的记忆不是一坨而是分层的。这个分层借鉴了认知科学里对人类记忆的分类但在工程上做了简化只保留三个最实用的层Working memory工作记忆就是当前对话的上下文窗口存放正在进行的任务状态、最近几轮的工具调用结果、当前的推理链。它的特点是容量有限、生命周期短、读写频繁。在实现上通常就是一个滑动窗口的message list配合一些状态标记。Episodic memory情景记忆存放的是“发生过什么”。每一轮任务执行结束后hindsight模块会把整个执行轨迹——包括用户输入、Agent的每一步决策、工具调用参数、返回结果、最终输出、以及是否成功——压缩成一条结构化的episode记录。这条记录不是原始日志的堆砌而是经过LLM摘要和标注的。Semantic memory语义记忆存放的是“学到了什么”。从多条episodic memory里提炼出来的通用规则、偏好、约束条件会沉淀到这一层。比如“用户不喜欢在周五下午安排会议”“调用某API时如果返回429需要退避3秒重试”“处理日期时默认时区是Asia/Shanghai”。这些条目是跨任务复用的。三层之间的关系是working memory在任务执行中实时读写任务结束后hindsight触发把working memory的执行轨迹压缩成episodic memory当episodic memory积累到一定数量或者检测到重复模式时触发semantic memory的提炼。注意不要一上来就搞三层全自动流转。我建议先把episodic memory做扎实semantic memory的提炼可以先用半自动方式——让LLM生成候选规则人工确认后再写入。全自动提炼在早期很容易把噪声当规律。2.2 为什么选MCP做工具调用层MCPModel Context Protocol在这套架构里的角色是工具调用的标准化接口。没有MCP之前每个Agent框架都有自己的tool定义格式换个框架就要重写一遍。MCP把这个层抽象出来了工具提供方实现一个MCP serverAgent侧实现一个MCP client双方通过标准协议通信。在hindsight场景下MCP的价值体现在两个地方。第一复盘工具本身可以是一个MCP server。比如我写了一个memory_write工具接收episode摘要和元数据写入向量库又写了一个memory_search工具接收查询文本返回相关记忆条目。这两个工具通过MCP暴露Agent在需要的时候调用不需要把记忆逻辑硬编码在Agent循环里。第二MCP让记忆层和业务工具层解耦。Agent在执行任务时调用的搜索工具、数据库工具、文件工具和复盘时调用的记忆工具走的是同一套协议。这意味着我可以在Docker里跑一个MCP server容器专门管记忆另一个容器跑业务工具Agent容器只负责编排。网络通了协议对了就能跑。2.3 Docker在这套架构里扮演什么角色Docker解决的是环境一致性和隔离性的问题。Agent系统通常要连向量数据库、要跑嵌入模型、要调外部API依赖一堆。本地开发跑通了换台机器就挂这种事太常见了。用Docker Compose把各个组件容器化至少保证开发、测试、部署三套环境的行为是一致的。具体到hindsight架构我通常拆成四个容器Agent主程序容器、MCP server容器记忆工具、向量数据库容器比如Qdrant或Chroma、以及可选的嵌入模型服务容器。四个容器在同一个Docker network里通过服务名互相访问。Agent容器不需要知道向量库的IP只需要知道MCP server的地址MCP server再去连向量库。这样做的好处是记忆层的存储和检索逻辑完全封装在MCP server里Agent侧只看到memory_write和memory_search两个工具。哪天我想把向量库从Chroma换成Qdrant只改MCP server的配置Agent代码一行不动。3. 实操落地从零搭一套带hindsight的Agent记忆系统3.1 环境准备与Docker Compose编排先说基础环境。我用的是一台Linux开发机Docker Engine 24以上Docker Compose v2。Windows用户建议用WSL2跑Docker Desktop注意在BIOS里开启虚拟化支持否则Docker Desktop启动时会报virtualization support not detected。这个坑我见过太多次了尤其是品牌整机默认关闭VT-x。目录结构这样组织hindsight-agent/ ├── docker-compose.yml ├── agent/ │ ├── Dockerfile │ └── main.py ├── mcp-memory/ │ ├── Dockerfile │ └── server.py └── data/ └── qdrant_storage/docker-compose.yml的核心内容version: 3.9 services: qdrant: image: qdrant/qdrant:latest volumes: - ./data/qdrant_storage:/qdrant/storage networks: - agent-net mcp-memory: build: ./mcp-memory environment: - QDRANT_URLhttp://qdrant:6333 - EMBEDDING_MODELall-MiniLM-L6-v2 depends_on: - qdrant networks: - agent-net agent: build: ./agent environment: - MCP_SERVER_URLhttp://mcp-memory:8080 - LLM_API_BASE${LLM_API_BASE} - LLM_API_KEY${LLM_API_KEY} depends_on: - mcp-memory networks: - agent-net networks: agent-net: driver: bridge这里有几个细节值得说。Qdrant的数据卷挂到宿主机容器重启不丢数据。MCP server通过环境变量拿Qdrant地址不硬编码。Agent容器通过MCP_SERVER_URL找MCP server走Docker内部DNS。LLM的API key从宿主机环境变量注入不写进镜像。提示如果你在Windows上跑路径挂载用./data/qdrant_storage这种相对路径通常没问题但如果遇到权限报错换成绝对路径并确保Docker Desktop的文件共享设置里包含了该盘符。3.2 MCP记忆服务的实现要点MCP server这边我用Python写核心是暴露两个工具memory_write和memory_search。框架上可以用官方的mcpPython SDK也可以用FastAPI自己包一层。我选后者因为调试方便日志好打。memory_write的入参设计很关键。我一开始只传了一个content字符串结果检索效果很差。后来改成结构化入参{ episode_id: uuid, task_summary: 用户要求订周五下午的会议室, outcome: success, # success / partial / failure key_decisions: [ {step: 3, decision: 选择会议室A, reason: 容量匹配}, {step: 5, decision: 改到14:00, reason: 用户偏好} ], lessons: [用户偏好下午2点后的时段], tags: [meeting, scheduling, preference], raw_trajectory_ref: s3://trajectories/xxx.json }task_summary和lessons字段会被嵌入模型编码后存入向量库tags和outcome作为payload字段用于过滤。raw_trajectory_ref指向原始轨迹的存储位置需要深挖的时候再去取。memory_search的入参是查询文本、top_k、以及可选的过滤条件。返回的是按相似度排序的记忆条目列表每条包含摘要、经验、以及相似度分数。嵌入模型我选的是all-MiniLM-L6-v2384维轻量在CPU上跑单条编码大概10毫秒。如果你的记忆条目很多上万条可以考虑换更大的模型或者上GPU但早期384维够用了。3.3 Agent侧的hindsight触发逻辑Agent主循环里hindsight的触发点是在一个episode结束之后。什么叫episode结束我的定义是用户的一个完整请求被处理完Agent给出了最终回复且没有待处理的工具调用。这时候触发复盘。复盘流程分四步第一步轨迹收集。把working memory里的message list、工具调用记录、中间状态快照打包。第二步LLM摘要。用一个专门的prompt让LLM生成结构化的episode记录。这个prompt我调了很多版核心是要求LLM输出JSON字段固定不要自由发挥。prompt里会给几个few-shot例子展示什么样的决策算“key decision”什么样的结论算“lesson”。第三步写入记忆。调用MCP的memory_write工具把结构化记录传过去。第四步清理working memory。把当前episode的临时状态清掉只保留必要的上下文衔接信息。这里有个容易忽略的点不是每个episode都值得写入记忆。如果任务太简单比如用户只是打了个招呼或者任务完全失败且没有可提炼的教训写入反而是噪声。我在Agent侧加了一个轻量判断如果工具调用次数少于2次且没有错误发生跳过hindsight。3.4 记忆检索的注入策略记忆写进去了怎么用在Agent处理新任务时第一步不是直接开始推理而是先用当前用户输入去memory_search拿回top 3到5条相关记忆注入到system prompt或者作为额外的context message。注入的位置有讲究。我试过三种方案注入位置效果问题system prompt末尾模型始终能看到占用固定token长对话时浪费第一条user message之前作为背景信息模型可能忽略动态插入到相关步骤前精准但实现复杂需要判断“相关步骤”目前我用的是第一种和第二种的结合在system prompt里放一个简短提示“你有历史经验可供参考”然后在第一条user message之前插入检索到的记忆条目。实测下来模型对user message之前的context利用率比system prompt末尾高。检索的top_k我设的是5相似度阈值0.65。低于阈值的直接丢弃宁可不给也不要给噪声。这个阈值是用一批标注数据调出来的不同嵌入模型和不同领域的数据阈值需要重新调。4. 踩坑记录与排查手册4.1 Docker网络不通的典型场景Docker Compose起来之后Agent容器访问MCP server报连接超时这是最高频的问题。排查顺序先确认容器都在同一个network里。docker compose ps看状态docker network inspect hindsight-agent_agent-net看容器列表。如果MCP server没在里面检查compose文件里的networks配置。再确认服务名解析。在Agent容器里执行ping mcp-memory如果不通说明DNS没生效。Docker Compose默认会给服务名做DNS但如果你手动指定了container_name且名字里有下划线可能会有问题。服务名用连字符别用下划线。最后确认端口。MCP server在容器里监听的是8080Agent连的也是8080但如果你在MCP server的Dockerfile里EXPOSE了别的端口或者server代码里bind的是127.0.0.1而不是0.0.0.0容器外部就连不上。bind地址必须是0.0.0.0。注意localhost在容器里指的是容器自己不是宿主机。Agent容器里连localhost:8080永远连不到MCP server。必须用服务名。4.2 记忆检索“答非所问”的调优检索回来的记忆和当前任务不相关这个问题我遇到过好几次。根因通常有三个一是嵌入模型不适合当前语言。all-MiniLM-L6-v2对中文的支持一般如果你的记忆条目主要是中文建议换paraphrase-multilingual-MiniLM-L12-v2或者BGE系列的中文模型。二是记忆条目写得太长。一条episode摘要如果超过500字嵌入向量会稀释关键信息。我的做法是强制摘要控制在200字以内lessons字段每条不超过50字。三是没有用metadata过滤。纯向量检索在数据量大时容易召回语义相近但场景不对的条目。加上tags过滤比如当前任务是scheduling就只检索tags里包含scheduling或calendar的条目准确率会明显提升。4.3 LLM摘要不稳定导致记忆质量波动用LLM做摘要输出格式偶尔会飘。明明要求JSON它给你返回一段markdown。这个问题在换模型或者调temperature之后尤其明显。我的解决方案是三层防护第一prompt里用JSON schema描述输出格式越具体越好第二调用LLM时开response_format{type: json_object}如果API支持第三解析失败时重试一次重试还失败就降级为纯文本存储标记format: raw后续检索时对这类条目降低权重。temperature我设的是0.1摘要任务不需要创造性。4.4 常见问题速查表现象可能原因排查动作Agent容器连不上MCP server网络不通/服务名错误/bind地址错误docker network inspect、容器内ping、检查bind记忆检索结果不相关嵌入模型语言不匹配/条目过长/缺过滤换模型、截断摘要、加tags过滤LLM摘要返回非JSONprompt不够具体/模型不支持JSON mode加schema描述、开JSON mode、重试Docker Desktop启动失败虚拟化未开启/WSL2未装BIOS开VT-x、装WSL2向量库数据丢失没挂volume检查compose里的volumes配置记忆写入重复episode_id没做去重写入前用episode_id查重5. 记忆架构的扩展方向与个人体会这套hindsight架构跑通之后我陆续做了一些扩展。一个是记忆的时效性衰减给每条记忆加一个last_accessed时间戳检索时对超过30天未被访问的条目降权。另一个是跨Agent的记忆共享多个Agent连同一个MCP memory server各自写入的episode打上agent_id标签检索时可以按agent过滤也可以全局检索。还有一个方向是semantic memory的半自动提炼。我写了一个定时任务每周跑一次把过去一周的episodic memory聚类对每个簇让LLM生成候选规则推送到一个审核队列。人工确认后的规则写入semantic memory在后续任务中作为硬约束注入。说实话这套东西的复杂度不低但收益是实打实的。最直观的变化是Agent在重复类任务上的错误率明显下降用户纠正过一次的事情第二次基本不会再犯。另一个意外收获是episodic memory积累多了之后可以用来做Agent行为的离线分析——哪些工具调用容易失败、哪些决策路径效率低一目了然。如果你刚开始搭我的建议是先把episodic memory这一层做扎实MCP server和Docker编排跑通检索注入调稳。semantic memory和自动提炼可以往后放等数据量上来了再说。别一上来就追求全自动人工介入在早期不是负担是质量保障。