LLM Agent 记忆架构实战：hindsight、MCP 与 Docker 部署

1. 从“hindsight”这个词说起：为什么它值得单独拿出来做

“hindsight”直译过来是“后见之明”，但在 LLM Agent 这个圈子里，它指向的是一个非常具体、也非常要命的问题：Agent 的记忆到底该怎么存、怎么取、怎么用。你如果最近在折腾 Agent 相关的东西，大概率已经被这几个词轮番轰炸过——agent memory、working memory、MCP、Docker。它们看起来各说各话，实际上全都指向同一件事：让 Agent 在多次交互之间“记住点什么”，并且在需要的时候能准确地想起来。

我最初注意到“hindsight”这个方向，是因为一个很现实的痛点。大部分 Agent Demo 跑单轮任务时表现惊艳，一旦把对话拉长到十几轮、几十轮，或者让它跨会话处理同一批数据，它就开始“失忆”——前面明确说过的约束，后面当没听见；上一轮已经排除的方案，下一轮又拿出来重试。这不是模型能力不够，而是记忆架构没设计好。而 hindsight 这个词本身就暗示了一种设计哲学：记忆的价值不在于“存下来”，而在于“事后能回看、能追溯、能复用”。

这篇内容适合谁看？如果你正在做 Agent 应用、在选型记忆存储方案、或者单纯被 MCP 和 Docker 这套组合拳搞得有点晕，那这篇就是写给你的。我会把 hindsight 背后的核心问题拆开讲：Agent 记忆到底分几层、working memory 和长期记忆怎么配合、MCP 在这里扮演什么角色、Docker 为什么几乎成了标配部署方式。全程不堆概念，尽量用我实际踩过的坑来说明每个选择背后的理由。

需要先说明一点：hindsight 目前没有一个官方钦定的“标准实现”，它更像是一个问题域——围绕 Agent 记忆的召回、追溯与上下文重建。所以下面讲的内容，是基于这个领域里已经被验证过的常见实践，加上我自己在项目里反复调整后沉淀下来的做法。你完全可以按自己的场景裁剪。

2. Agent 记忆的三层结构：别再把所有东西塞进一个向量库

很多人一提 Agent 记忆，第一反应就是“上个向量数据库”。这个思路没错，但太粗。真正跑起来你会发现，把所有记忆一股脑塞进向量库，检索质量会随着数据量增长而急剧下降，而且成本高、延迟大。我后来把记忆拆成三层来管，效果稳定很多。

2.1 Working Memory：当前任务的“草稿纸”

Working memory 是 Agent 在当前任务周期内的工作记忆，可以理解成它的“草稿纸”。这一层的特点是：生命周期短、读写频繁、容量有限。它存的不是知识，而是当前任务的中间状态——比如用户刚提到的约束条件、已经调用过的工具及返回结果、当前推理链的关键节点。

我一般用两种方式实现 working memory。轻量场景直接放在对话上下文里，靠 prompt 拼接维护；重一点的场景会单独开一个结构化的状态对象，比如一个 JSON，里面分字段存constraints、tool_results、open_questions。为什么不用纯文本？因为纯文本在长对话里会被模型“稀释”，而结构化字段可以在每轮 prompt 里精准注入，模型不容易忽略。

这里有个我踩过的坑：working memory 不要无脑全量注入。我早期图省事，把整个状态对象每轮都塞进 prompt，结果 token 消耗飙升，而且模型开始“分心”——它会去关注一些当前轮次根本用不上的历史字段。后来改成按当前意图动态筛选字段，只注入相关部分，效果立刻好转。这个筛选逻辑本身可以用一个轻量规则引擎，也可以让模型自己判断，看你的延迟预算。

2.2 Episodic Memory：带时间戳的“事件流”

Episodic memory 是情节记忆，存的是“发生过什么”。每一次任务执行、每一次用户交互，都可以作为一条 episode 记录下来，带上时间戳、任务类型、结果状态。这一层的核心价值是可追溯——当 Agent 需要回答“上次我们是怎么处理这个问题的”时，它能翻出具体的事件记录。

实现上我倾向于用关系型存储或者文档存储，而不是纯向量库。原因很简单：episodic memory 的查询往往带结构化条件，比如“最近三天内失败的订单处理任务”，这种查询用 SQL 或文档查询比向量相似度靠谱得多。向量检索适合模糊语义匹配，但不适合精确的时间/状态过滤。

提示：episodic memory 一定要带“结果状态”字段。成功、失败、部分成功、被用户中断，这些状态在后续召回时权重完全不同。我见过不少实现只存了内容不存状态，导致 Agent 把失败的经验当成成功经验复用，直接翻车。

2.3 Semantic Memory：沉淀下来的“知识”

Semantic memory 是语义记忆，存的是从多次 episode 中提炼出来的稳定知识。比如“这个用户偏好简洁回复”“这类报错通常是因为配置缺失”。它和 episodic 的区别在于：episodic 是原始事件，semantic 是归纳后的结论。

这一层才是向量库真正该发挥作用的地方。因为 semantic memory 的查询大多是语义相似度匹配——“有没有和当前情况类似的经验”。但要注意，semantic memory 的写入不能太频繁，否则会引入大量噪声。我的做法是定期批量提炼，比如每积累 N 条 episode，或者每天定时跑一次归纳任务，把重复出现的模式抽成 semantic 条目。

三层之间的关系可以这样理解：working memory 是正在写的草稿，episodic memory 是流水账日记，semantic memory 是读日记后总结出的心得。hindsight 的核心，就是让这三层能顺畅地互相喂养——草稿完成后归档成日记，日记积累后提炼成心得，心得又在下次任务开始时反哺草稿。

3. MCP 在记忆架构里的真实位置：它不是存储，是“接口标准”

MCP 这个词最近出现频率极高，但很多人对它的定位是模糊的。我一开始也以为它是个存储方案，后来才理清楚：MCP 是一套让模型和外部能力对接的协议标准，它管的是“怎么调用”，不是“存在哪”。把它和记忆存储混为一谈，是选型时最容易犯的错。

3.1 MCP 解决的是“工具接入碎片化”问题

在没有 MCP 之前，你要让 Agent 调用一个外部工具，得为每个工具写适配代码：这个工具用 REST，那个用 gRPC，还有一个是本地命令行。每接一个新工具就是一次重复劳动。MCP 的思路是定义一套统一的描述格式和调用约定，工具方按这个标准暴露能力，Agent 方按这个标准去发现和调用。

放到记忆场景里，MCP 的价值在于：它让记忆的读写变成一种标准化的“工具调用”。你的记忆存储可以是一个 MCP server，Agent 通过 MCP 协议去store、retrieve、search。这样一来，记忆层和 Agent 逻辑就解耦了——你换存储实现，只要 MCP 接口不变，Agent 侧几乎不用改。

3.2 记忆类 MCP server 该暴露哪些能力

我实际设计过一个记忆 MCP server，暴露的核心方法大概这几类：

这里有个设计细节值得说：memory.search的返回结果不要只返回内容，要带上来源标识和置信度。因为 Agent 在后续推理时需要判断“这条记忆可不可信”。我早期版本只返回文本，结果模型把一条低置信度的旧记忆当成了铁律，导致决策偏差。加上置信度和时间戳之后，模型自己就能做加权判断。

3.3 MCP 和 working memory 的关系

有人会问：working memory 那么短命，也需要走 MCP 吗？我的答案是看情况。如果 working memory 完全在 Agent 进程内维护，那没必要走 MCP，直接内存操作更快。但如果你的 Agent 是多进程、多实例部署的，working memory 需要跨实例共享，那走 MCP 统一管理反而更清晰。

我现在的做法是：进程内的临时状态直接内存维护，需要跨会话或跨实例的部分才走 MCP。这样既保留了低延迟，又保证了可扩展性。别为了“架构统一”把所有东西都塞进 MCP，那会引入不必要的网络开销。

4. Docker 部署记忆服务：为什么它几乎成了默认选项

聊到部署，Docker 基本绕不开。你搜“docker 安装”“docker compose”“windows 安装 docker”这些词的热度就知道，它是当前最主流的服务打包方式。对于 Agent 记忆服务来说，Docker 的价值不只是“方便”，而是环境一致性——记忆服务往往依赖特定的向量库版本、特定的 Python 运行时，裸机部署很容易出现“我本地能跑，服务器上不行”。

4.1 用 Docker Compose 编排记忆服务栈

一个典型的记忆服务栈通常包含：记忆服务本体、向量数据库、关系型数据库（存 episodic）、可能还有一个缓存。用 Docker Compose 编排是最省心的方式。下面是我常用的一个 compose 结构示意：

services: memory-service: build: ./memory ports: - "8080:8080" environment: - VECTOR_DB_URL=http://vector-db:6333 - RELATIONAL_DB_URL=postgresql://user:pass@relational-db:5432/memory depends_on: - vector-db - relational-db vector-db: image: qdrant/qdrant:latest volumes: - vector_data:/qdrant/storage relational-db: image: postgres:16 environment: - POSTGRES_PASSWORD=pass volumes: - pg_data:/var/lib/postgresql/data volumes: vector_data: pg_data:

这个结构的好处是依赖关系显式声明，depends_on保证启动顺序，volume 保证数据持久化。我踩过的坑是：早期没挂 volume，容器一重启数据全没，调试时反复重建索引，浪费了大量时间。记忆服务的数据是核心资产，持久化必须做。

4.2 Windows 上跑 Docker 的几个真实坑

如果你在 Windows 上开发，Docker Desktop 是常见选择，但有几个坑我踩得很深。第一是虚拟化支持，如果 BIOS 里没开虚拟化，Docker Desktop 直接起不来，报错信息还比较隐晦。第二是WSL2 后端和 Hyper-V 后端的切换，不同后端对网络和文件挂载的行为不一样，我建议统一用 WSL2 后端，文件性能更好。

第三是网络不通问题。容器之间要互相访问，必须保证在同一个 Docker network 里。我遇到过 memory-service 访问不到 vector-db 的情况，排查半天发现是 compose 里没声明共享网络，两个服务各自在默认网络里。解决办法很简单，在 compose 顶层加一个networks声明，每个服务都挂上同一个网络。

注意：Windows 下挂载本地目录到容器时，路径要用正斜杠或者转义后的反斜杠，而且跨文件系统的 IO 性能会明显下降。记忆服务的数据库文件尽量放在 Docker volume 里，不要挂到 Windows 宿主机目录。

4.3 镜像分层与构建缓存

记忆服务的镜像构建有个优化点：把依赖安装和代码拷贝分开。先拷贝requirements.txt或package.json装依赖，再拷贝源码。这样改代码时不会触发依赖重装，构建速度快很多。我早期把整个项目一次性 COPY 进去，每次改一行代码都要重装一遍依赖，构建时间从十几秒变成几分钟，非常影响迭代节奏。

5. 记忆召回的质量控制：hindsight 真正的难点所在

存下来容易，取对了难。hindsight 这个词的精髓就在“回看”这一步——能不能在正确的时机，把正确的记忆，以正确的形式喂给模型。这一步做不好，前面存得再漂亮都是白搭。

5.1 召回不是“相似度排序”这么简单

新手最容易犯的错，是把召回等同于“向量相似度 top-k”。实际跑起来你会发现，相似度最高的那条记忆，往往不是当前最该用的那条。原因有几个：语义相似不等于情境相关；旧记忆可能已经过时；高相似度的记忆可能是失败经验。

我现在的召回策略是多路召回 + 重排。多路包括：向量相似度召回、时间近邻召回、结构化条件召回（比如同任务类型）。然后把多路结果合并，用一个重排模型或规则打分。打分维度至少包含：语义相关度、时间新鲜度、结果状态（成功优先）、使用频次（被验证过的优先）。

5.2 上下文注入的“预算管理”

召回出来的记忆不能全塞进 prompt，token 是有预算的。我一般给记忆部分分配一个固定的 token 上限，比如总上下文的 30%。然后按打分排序，从高到低填充，直到接近上限。这里有个技巧：给每条记忆标注一个“压缩版本”，当预算紧张时用压缩版，预算充足时用完整版。压缩版可以是摘要，也可以是关键字段的拼接。

这个预算管理听起来简单，但它是保证 Agent 在长对话里不崩的关键。我见过太多项目因为无节制注入记忆，导致 prompt 超长、模型注意力涣散、响应变慢，最后整个体验垮掉。

5.3 记忆的“遗忘”机制

有存就得有删。不是所有记忆都值得长期保留。我设计遗忘机制时考虑三个维度：时间衰减、访问频率、结果价值。长期不被访问、且结果价值低的记忆，逐步降权甚至归档删除。这样能控制记忆库的规模，保证召回质量不随时间稀释。

具体实现上，我给每条记忆一个decay_score，随时间衰减，每次被成功召回并产生正向结果时加分。低于阈值的记忆进入“冷存储”，不再参与常规召回，但保留可追溯性。这个机制让我的记忆库在跑了几个月后依然保持较高的召回精度。

6. 一套可复现的最小记忆服务搭建流程

讲了这么多原理，最后给一套能直接上手的最小流程。目标：搭一个带 working memory、episodic memory、semantic memory 三层，通过 MCP 暴露接口，用 Docker Compose 编排的记忆服务。

6.1 环境准备与依赖确认

先确认 Docker 和 Docker Compose 可用。Windows 用户确认 Docker Desktop 已启动，虚拟化已开启。然后准备项目目录结构：

memory-stack/ docker-compose.yml memory-service/ Dockerfile requirements.txt app/ main.py memory.py mcp_server.py

requirements.txt里核心依赖：MCP 协议库、向量库客户端、关系库驱动、Web 框架。版本要锁死，避免构建时拉到不兼容的新版本。

6.2 记忆服务核心逻辑

memory.py里实现三层记忆的读写。working memory 用进程内字典，episodic 写关系库，semantic 写向量库。关键函数包括write_episode、search_semantic、get_working_state。每个函数都要处理异常——记忆服务挂了不能拖垮整个 Agent，要有降级策略，比如召回失败时返回空列表而不是抛异常。

6.3 MCP 接口暴露

mcp_server.py里按 MCP 标准注册方法。每个方法要有清晰的参数 schema 和返回 schema。我建议在返回里统一带上source、confidence、timestamp三个字段，方便 Agent 侧做判断。注册完成后本地起服务，用 MCP 客户端测一遍每个方法，确认参数和返回符合预期。

6.4 启动与验证

docker compose up -d启动整个栈。然后用docker compose logs -f memory-service看日志，确认服务正常监听、数据库连接成功。接着跑一个简单的写入-召回测试：写一条 episode，等几秒，再搜一下，看能不能召回。这一步能跑通，说明基础链路没问题。

6.5 接入 Agent 并观察真实表现

最后把 MCP server 地址配到你的 Agent 里，跑一个多轮任务，观察记忆是否被正确写入和召回。重点看两个指标：召回命中率（该用的记忆有没有被取出来）和噪声率（取出来的记忆有多少是无关的）。这两个指标决定了记忆架构的实际价值。我一般会跑几十轮对话来观察，单轮测试看不出问题。

7. 几个我反复验证过的经验点

第一，记忆类型一定要分开存。混在一起存，召回时没法按类型过滤，噪声会非常大。分开之后，你可以针对不同任务只召回特定类型，精度提升明显。

第二，写入时机比写入内容更重要。不是每轮对话都值得写记忆。我一般只在任务完成、用户给出明确反馈、或者出现异常时写入。频繁写入会污染记忆库。

第三，MCP 接口要版本化。记忆服务的接口一旦被多个 Agent 依赖，改起来就很麻烦。我在接口路径里带了版本号，新老版本并行一段时间，平滑迁移。

第四，Docker 镜像要固定基础镜像版本。用latest标签迟早会出问题，某天基础镜像更新了，你的构建突然就挂了。固定到具体版本号，构建可复现。

第五，给记忆服务加健康检查。Docker Compose 支持 healthcheck，配上之后，依赖它的服务会等它真正就绪再启动，避免启动顺序导致的连接失败。这个配置我每个项目都会加，省去很多“为什么连不上”的排查时间。

这套东西跑顺之后，你会发现 Agent 的“记性”问题基本解决了大半。剩下的就是根据具体业务场景调召回策略和打分权重，那是个持续优化的过程，没有一劳永逸的配置。我自己也是跑了几个月，才把召回精度调到比较满意的水平。