Hindsight 实战：用 Docker 和 MCP 为 LLM Agent 构建分层记忆系统

1. 从“事后诸葛亮”说起：hindsight 到底想解决什么问题

第一次看到hindsight这个词，我脑子里蹦出来的就是“事后诸葛亮”。英文里 hindsight 指的就是回头看、事后才明白。把这个词用在 agent memory 这个方向上，其实非常精准——大模型智能体最缺的能力之一，就是“回头看”。

我们先把场景摆出来。你搭了一个基于 LLM 的 agent，接了一堆工具，跑得挺欢。但用着用着你就会发现几个特别难受的地方：第一，它记不住上一轮对话里你明确纠正过的东西，下一轮又犯同样的错；第二，它记不住自己做过什么，任务做到一半断了，重启之后一脸茫然；第三，它记不住“哪些做法上次失败了”，于是反复踩同一个坑。这三个问题，本质上都是记忆问题，而且是不同层次的记忆问题。

hindsight这个项目，从标题和关联热词来看，核心就是围绕agent memory做文章，并且和LLM、MCP、Docker这几个关键词强绑定。热词里还出现了a-memguard: a proactive defense framework for llm-based agent memory，这说明 agent memory 这个方向已经不只是“存和取”的问题，还延伸到了“记忆安全”和“记忆防御”。同时agent 存储 working memory、llm wiki知识库、llm wiki、karpathy llm wiki这些词，又指向了另一个思路：把记忆组织成类似 wiki 的结构化知识，而不是简单的向量堆砌。

所以这篇博文，我想做的事情是：把hindsight这个方向拆开，讲清楚一个 agent memory 系统到底该怎么设计、怎么落地、怎么用 Docker 跑起来、怎么通过 MCP 接进现有的 LLM 工具链，以及在这个过程中我踩过哪些坑。适合谁看？适合已经能跑通一个基础 agent、但被“记不住事”折磨过的开发者；也适合想了解 MCP 协议和 agent 记忆架构的技术爱好者。哪怕你只是刚装完 Docker，也能从里面的部署部分抄到能用的作业。

我个人的判断是：agent memory 不是加一个向量数据库就完事。向量库解决的是“语义相似检索”，但 agent 需要的是分层记忆——working memory、episodic memory、semantic memory，甚至还要有“反思”机制。hindsight 这个名字暗示的，恰恰是让 agent 具备“回看自己历史、从中提炼经验”的能力。下面我按这个思路一层层展开。

2. 核心架构拆解：agent memory 为什么要分层

2.1 从 working memory 说起，别一上来就上向量库

很多人做 agent memory，第一反应就是“接个向量数据库”。我早期也这么干过，结果就是：agent 每次都要去向量库里捞一堆语义相似的片段，捞回来的东西又长又杂，塞进 context 之后反而把真正重要的当前任务信息挤掉了。这就是典型的“记忆过载”。

正确的做法是先分清记忆的层次。我参考认知科学里比较通用的分法，结合工程实践，把 agent memory 分成这么几层：

hindsight的价值，我认为主要落在Episodic和Reflective这两层。因为 working memory 靠 context window 就能凑合，semantic memory 靠向量库也能凑合，但“记住自己做过什么、并从中反思”这件事，绝大多数 agent 框架是缺失的。

提示：不要试图用一层记忆解决所有问题。我见过太多项目把对话历史、知识库、任务状态全塞进一个向量库，最后检索质量一塌糊涂。分层是刚需，不是过度设计。

2.2 hindsight 的“回看”机制：让 agent 学会复盘

hindsight 这个词的精髓在于“事后回看”。落到工程上，就是 agent 在完成一个任务或者一段会话之后，触发一个复盘流程：把这段时间的 episodic memory 拿出来，让 LLM 总结成几条经验，写回 reflective memory。下次遇到类似任务时，先把这些经验注入 context。

这个机制听起来简单，但有几个关键设计点：

第一，触发时机。不能每轮都复盘，那样 token 成本爆炸。我的做法是任务结束时触发一次，或者会话空闲超过一定时间触发。也可以设置一个“重要事件”标记，遇到关键决策点时单独复盘。

第二，复盘内容的粒度。太细了没价值，太粗了没用。我一般让 LLM 输出“情境-行动-结果-教训”四元组，这样下次检索时能精准匹配情境。

第三，经验的淘汰。reflective memory 会越积越多，必须有淘汰机制。我用的策略是给每条经验加一个“命中计数”和“最后命中时间”，长期没被检索到的经验降权甚至归档。

这里就体现出a-memguard那类防御框架的意义了：如果 agent 的记忆可以被外部输入污染，那它复盘出来的“经验”可能就是错的，甚至会引导 agent 做出危险行为。所以记忆写入前要做校验，尤其是来自外部工具返回的内容，不能直接当成事实写进 semantic memory。

2.3 为什么是 MCP：记忆系统不该是孤岛

热词里MCP出现频率极高，mcp协议、mcp server、mcp教程、playwright mcp、blurpsuite mcp、blender mcp、yakit mcp一大堆。这说明 MCP 已经成了 LLM 工具生态里的事实标准之一。

MCP 是什么？简单说，它是一个让 LLM 应用和外部能力（工具、数据源、服务）对接的协议。你可以把它理解成“AI 世界的 USB-C 接口”——不管对面是数据库、浏览器、还是某个 SaaS，只要实现了 MCP server，LLM 客户端就能用统一的方式调用。

把 hindsight 做成一个 MCP server，好处非常直接：你的记忆系统不用关心上层是哪个 LLM 框架，Claude Desktop 能接、自研 agent 能接、各种 IDE 插件也能接。记忆变成了一个独立的、可复用的服务。这比把记忆逻辑硬编码在某个 agent 框架里要优雅得多。

我实测下来，MCP 接入记忆系统最舒服的一点是：工具调用和记忆读写可以走同一套协议。agent 调用一个工具做完事，顺手就把这次调用的结果写进 episodic memory，全程不用切换通信方式。

2.4 Docker 在其中的角色：一键起一套记忆服务

热词里docker、docker desktop、docker安装、docker安装教程、windows安装docker、linux安装docker、docker网络不通、virtualization support not detected这些词扎堆出现，说明大量人在部署环节卡住了。

hindsight 这类记忆服务，依赖通常不少：可能要向量库、要关系库、要缓存、要 MCP server 本体。手工装一遍，环境差异能把你逼疯。用 Docker Compose 把整套东西编排起来，是最省心的方案。后面我会给一份可以直接抄的 compose 配置。

3. 核心细节解析：记忆的写入、检索与反思怎么实现

3.1 记忆写入：别把原始对话直接倒进去

我见过最粗暴的做法，是把每轮对话原封不动存进数据库。这么干短期能跑，长期就是灾难——检索出来的全是冗余对话，信噪比极低。

合理的写入流程应该包含这么几步。第一步是切分，把长对话按语义切成片段，而不是按固定字数硬切。第二步是抽取，用 LLM 从片段里抽出结构化信息：谁、在什么情境下、做了什么、结果如何。第三步是去重，新信息和已有记忆做相似度比对，高度重复的就合并或跳过。第四步是打标，给记忆打上时间、任务类型、涉及工具、成功失败等标签，方便后续过滤检索。

这里有个实操细节：抽取这一步的 prompt 非常关键。我试过好几种写法，最后稳定下来的模板大概是让模型输出 JSON，字段固定为situation、action、outcome、lesson、tags。字段固定之后，下游处理就简单了，不用每次解析自由文本。

注意：写入前一定要做一次“事实性校验”。尤其是工具返回的内容，可能包含错误或恶意注入。我的做法是让一个独立的 LLM 调用判断“这条信息是否可信、是否与已有记忆冲突”，冲突的进人工审核队列，而不是直接覆盖。

3.2 记忆检索：混合检索比纯向量靠谱

纯向量检索的问题在于，它对“精确匹配”不敏感。比如你要找“上次用 playwright 抓取某网站失败的原因”，向量检索可能给你返回一堆“浏览器自动化”相关的泛泛内容，但真正那条失败记录反而排后面。

我的方案是混合检索：向量相似度 + 关键词匹配 + 标签过滤，三路结果用加权融合排序。权重可以这么设：向量 0.5，关键词 0.3，标签 0.2。具体数值要根据你的数据调，但混合的思路是通用的。

另外，检索时要带上时间衰减。越近的记忆权重越高，这符合直觉。我一般用指数衰减，半衰期设成 7 天左右。这样既保留了长期记忆，又让近期经验优先。

还有一个技巧是情境预过滤。检索前先用当前任务的类型、涉及的工具做一次粗筛，把候选集缩小，再做精细排序。这样既快又准。

3.3 反思生成：让 LLM 当自己的教练

反思这一步，本质上是让 LLM 扮演教练角色，回看运动员（agent）的比赛录像，给出改进建议。prompt 设计上，我会明确要求它回答三个问题：这次任务哪里做得好？哪里可以改进？下次遇到类似情况应该怎么做？

输出同样结构化，每条反思带一个confidence字段，表示模型对这条经验的置信度。置信度低的经验，检索时降权。这样能过滤掉一部分模型“瞎总结”的内容。

反思的频率我建议不要太高。实测下来，每个任务结束反思一次，token 成本可以接受；如果每轮对话都反思，成本会翻好几倍，而且很多反思是重复的。

3.4 记忆安全：a-memguard 思路的借鉴

a-memguard这个方向提醒我们，agent memory 是有攻击面的。攻击者可以通过工具返回、用户输入等渠道，往记忆里注入虚假信息，诱导 agent 后续做出错误决策。

防御思路我总结了几条。一是来源标记，每条记忆记录来源，外部来源的记忆默认低信任。二是交叉验证，重要事实需要多个来源印证才写入 semantic memory。三是定期审计，用 LLM 扫描记忆库，找出矛盾或异常条目。四是写入限流，防止短时间内大量注入。

这些机制会增加复杂度，但对于要长期运行、处理敏感任务的 agent 来说，是值得的。

4. 实操落地：用 Docker + MCP 把 hindsight 跑起来

4.1 环境准备：先把 Docker 这关过了

热词里virtualization support not detected docker desktop failed to start这个问题出现频率很高，我先把这个坑填了。这个报错的意思是系统没开启硬件虚拟化。Windows 下要去 BIOS/UEFI 里开启 VT-x 或 AMD-V，然后在“启用或关闭 Windows 功能”里确认勾选了“虚拟机平台”和“适用于 Linux 的 Windows 子系统”。开启后重启，Docker Desktop 一般就能起来了。

Linux 下装 Docker，我习惯用官方脚本：

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER

最后一行是把当前用户加进 docker 组，免得每次都要 sudo。执行完要重新登录才生效。

docker网络不通也是高频问题。多数情况是防火墙或者 iptables 规则挡了。排查顺序是：先docker network ls看网络在不在，再docker network inspect看容器有没有正确接入，最后检查宿主机防火墙。我遇到过一例是公司网络策略限制了 docker0 网桥的流量，改成自定义 bridge 网络就好了。

4.2 用 Docker Compose 编排记忆服务

下面这份 compose 是我实际用过的精简版，包含记忆服务本体、Postgres（存结构化记忆）、Redis（存 working memory）、以及一个向量库。你可以按需删减。

version: "3.9" services: hindsight: image: hindsight-memory:latest build: . ports: - "8765:8765" environment: - DB_URL=postgresql://mem:mem@postgres:5432/hindsight - REDIS_URL=redis://redis:6379/0 - VECTOR_URL=http://qdrant:6333 - LLM_API_BASE=${LLM_API_BASE} - LLM_API_KEY=${LLM_API_KEY} depends_on: - postgres - redis - qdrant networks: - memnet postgres: image: postgres:16 environment: - POSTGRES_USER=mem - POSTGRES_PASSWORD=mem - POSTGRES_DB=hindsight volumes: - pgdata:/var/lib/postgresql/data networks: - memnet redis: image: redis:7-alpine command: redis-server --appendonly yes volumes: - redisdata:/data networks: - memnet qdrant: image: qdrant/qdrant:latest volumes: - qdrantdata:/qdrant/storage networks: - memnet volumes: pgdata: redisdata: qdrantdata: networks: memnet: driver: bridge

几个关键点解释一下。LLM_API_BASE和LLM_API_KEY用环境变量注入，不要硬编码在 compose 里，这是基本安全习惯。depends_on只保证启动顺序，不保证服务就绪，所以记忆服务本体里最好加一个重试逻辑，连不上数据库就等几秒再试。自定义 bridge 网络memnet是为了避免和宿主机其他容器网络冲突，也顺便绕开一部分网络不通的问题。

启动命令就一句：

docker compose up -d

然后docker compose logs -f hindsight看日志，确认服务起来了。

4.3 把记忆服务暴露成 MCP Server

MCP server 的实现方式，取决于你用的语言。Python 生态里，官方有 SDK 可以用。核心是定义几个 tool：write_memory、search_memory、reflect、list_recent。每个 tool 有明确的输入 schema，LLM 客户端就能自动发现并调用。

一个简化的 tool 定义大概长这样：

from mcp.server import Server from mcp.types import Tool, TextContent server = Server("hindsight-memory") @server.list_tools() async def list_tools(): return [ Tool( name="write_memory", description="写入一条结构化记忆", inputSchema={ "type": "object", "properties": { "situation": {"type": "string"}, "action": {"type": "string"}, "outcome": {"type": "string"}, "lesson": {"type": "string"}, "tags": {"type": "array", "items": {"type": "string"}} }, "required": ["situation", "action", "outcome"] } ), Tool( name="search_memory", description="检索相关记忆", inputSchema={ "type": "object", "properties": { "query": {"type": "string"}, "top_k": {"type": "integer", "default": 5} }, "required": ["query"] } ) ]

这里有个坑要注意：inputSchema一定要写规范，字段类型、必填项都要明确。我遇到过llm request failed: provider rejected the request schema or tool payload这个报错，排查半天，最后发现是 schema 里有个字段类型写成了"string"但实际传的是数组。schema 校验很严格，别偷懒。

4.4 接入现有 LLM 工具链

MCP server 跑起来之后，接入就简单了。以常见的桌面客户端为例，在配置里加上 server 的地址和启动方式即可。如果是本地 stdio 方式，配置里写启动命令；如果是 SSE 或 WebSocket 方式，写 URL。

热词里出现了wss://api.xiaozhi.me/mcp/?token=...这种形式，说明远程 MCP server 用 WebSocket 接入也是常见做法。远程接入的好处是记忆服务可以集中部署，多个客户端共享同一份记忆。但要注意鉴权，token 不要泄露，最好加上来源限制。

接入之后，建议先做一次连通性测试：让 agent 调用write_memory写一条，再调用search_memory查出来。跑通这条链路，后面就顺了。

5. 常见问题与排查技巧实录

5.1 记忆检索不准，怎么办

这是最高频的问题。排查思路按顺序来：先看写入质量，如果写进去的就是一堆原始对话，检索肯定不准；再看检索策略，纯向量换成混合检索；再看时间衰减，是不是老记忆把新记忆压住了；最后看标签体系，标签太粗或太细都会影响过滤效果。

我踩过的一个坑是：embedding 模型换了之后，旧记忆的向量和新查询的向量不在同一空间，检索结果全乱。换 embedding 模型一定要重新索引全部记忆，别偷懒。

5.2 记忆越积越多，性能下降

这是必然的，要有归档机制。我的做法是：超过一定时间且命中次数低于阈值的记忆，移到冷存储，检索时默认不查，需要时再手动查。另外向量库要定期做索引优化，Qdrant 和同类产品都有 compaction 相关的配置。

5.3 Docker 容器起来了但服务连不上

先docker compose ps看容器状态，再看日志。常见原因有三个：端口映射写错、服务启动比依赖慢、网络配置冲突。我一般会在记忆服务里加一个健康检查接口，compose 里配healthcheck，这样依赖服务就绪后才启动。

5.4 MCP 工具调用报 schema 错误

前面提过，schema 要严格。另外注意不同客户端对 MCP 协议的实现版本可能不同，字段支持程度有差异。遇到报错，先把 schema 简化到最小可用，跑通再逐步加字段。

5.5 常见问题速查表

5.6 几条独家避坑心得

第一条，别在记忆服务里做太多 LLM 调用。写入时抽取、反思时总结，这两处用 LLM 就够了。检索路径上尽量别调 LLM，否则延迟会很难看。

第二条，给记忆加版本号。记忆结构会演进，加个 schema 版本字段，升级时好做迁移。

第三条，日志要记全。记忆的写入、检索、反思都要打日志，出问题时能回溯。我吃过没日志的亏，排查一个检索异常花了一整天。

第四条，先跑通最小闭环再优化。别一上来就搞知识图谱、搞多路召回。先把“写入-检索-注入 context”这条链路跑通，再逐步加复杂度。

6. 记忆系统的扩展方向

跑通基础版之后，有几个方向可以继续深挖。一个是把 semantic memory 做成真正的知识图谱，实体和关系都结构化，检索时能做多跳推理。热词里llm ontology、llm wiki、karpathy llm wiki指向的就是这个方向——把知识组织成 wiki 式的互联结构，而不是孤立片段。

另一个方向是记忆的共享与协作。多个 agent 共享同一份记忆库，各自的经验能互相借鉴。这在多 agent 系统里很有价值，但也要处理好冲突和权限。

还有一个方向是记忆的可解释性。让 agent 能说清楚“我为什么这么做”，答案往往就藏在它的记忆里。把检索到的记忆和决策过程关联起来，调试和审计都会方便很多。

我自己在实际操作中的体会是：agent memory 这件事，难的不是技术选型，而是想清楚“什么该记、什么该忘、怎么用”。hindsight 这个名字给了一个很好的提醒——让 agent 学会回头看，比让它记住一切更重要。记忆不是越多越好，而是越准越好。