1. 从“hindsight”说起：为什么记忆是 Agent 落地的最后一公里

“hindsight”这个词本身很有意思，字面意思是“事后的洞察”，也就是我们常说的“后见之明”。把它作为项目标题，放在 agent memory 这个语境下，指向性其实非常明确：让 LLM Agent 具备对历史交互的回溯、沉淀与再利用能力。换句话说，不是让模型变聪明，而是让它“记得住、想得起、用得上”。

我接触过不少做 Agent 的团队，模型选型、工具调用、MCP 协议对接这些环节都跑通了，demo 演示也很漂亮，但一到真实业务场景就露馅。用户上周提过的偏好，这周再问，Agent 一脸茫然；同一个任务反复执行，每次都从零开始，token 烧得飞快，效果还不稳定。问题的根子不在模型能力，而在记忆层缺失。Agent 存储 working memory 这件事，看起来是个工程细节，实际上决定了产品能不能从“玩具”变成“工具”。

这个项目适合谁看？如果你正在用 LLM 框架搭 Agent，已经接了 MCP 协议、跑通了 Docker 部署，但发现多轮对话一长就失忆、任务连续性差、成本压不下来，那这篇内容就是给你准备的。我会从整体设计思路讲到具体落地，包括 Docker 环境、MCP 对接、记忆分层、检索策略，以及我在实操中踩过的坑。不堆概念，只讲能直接抄作业的东西。

2. 整体设计思路：Agent 记忆到底该怎么分层

2.1 为什么不能只靠上下文窗口硬扛

很多人第一反应是：上下文窗口不是越来越大了吗，128K、200K 甚至 1M，直接把历史全塞进去不就行了？我一开始也这么想过，实测下来问题很多。首先是成本，token 是按量计费的，每次请求都把几万 token 的历史带上，账单会教你做人。其次是注意力稀释，上下文越长，模型对关键信息的召回率反而下降，这在业界已经有不少验证。最后是延迟，长上下文的推理时间明显增加，交互体验直接崩掉。

所以正确的做法是分层。我在项目里把 Agent 记忆分成三层：working memory（工作记忆）、episodic memory（情景记忆）、semantic memory（语义记忆）。working memory 就是当前会话的短期上下文，容量小、更新快；episodic memory 存的是历史交互片段，按时间线组织；semantic memory 则是从交互中抽取出来的结构化知识，比如用户偏好、实体关系、任务模板。这三层各司其职，检索时按需调用，而不是一股脑全塞给模型。

2.2 hindsight 的核心机制：回溯与固化

hindsight 这个项目的关键设计在于“回溯”和“固化”两个动作。回溯是指 Agent 在需要时能主动查询历史记忆，而不是被动等待上下文携带；固化是指把有价值的交互内容从 working memory 沉淀到长期存储，避免会话结束后就丢失。

具体来说，每轮对话结束后，系统会跑一个轻量的抽取流程，判断这轮交互里有没有值得记住的信息。判断标准包括：是否包含用户明确表达的偏好、是否涉及任务关键参数、是否是重复出现的模式。符合条件的，写入 episodic memory，同时触发一次语义抽取，更新 semantic memory。这个过程是异步的，不阻塞主对话流程，所以对响应速度影响很小。

提示：抽取流程不要用太重的模型，我一开始用大模型做抽取，延迟高、成本也高，后来换成小模型加规则兜底，效果够用，成本降了一个数量级。

2.3 存储选型：为什么是向量库加关系库的组合

记忆存储这块，我试过纯向量库、纯关系库、以及两者组合。纯向量库检索语义相似度很方便，但做精确过滤（比如按时间范围、按用户 ID）很别扭；纯关系库结构化查询强，但语义召回弱。最后落地的是组合方案：向量库存记忆片段的 embedding，关系库存元数据（时间戳、用户 ID、任务类型、重要度评分）。检索时先用关系库做粗筛，再用向量库做语义排序，两全其美。

这个组合在 Docker 环境下部署也不复杂，向量库我用的轻量方案，关系库就是常规的 PostgreSQL，两个容器通过 Docker 网络互通。这里要注意 Docker 网络配置，容器间通信要用自定义 bridge 网络，不要用默认的，否则容易出现网络不通的问题。

3. 核心细节解析：MCP 协议在记忆系统里的角色

3.1 MCP 是什么，为什么记忆系统需要它

MCP 全称是 Model Context Protocol，是一个让模型和外部工具、数据源对接的协议标准。你可以把它理解成 Agent 世界的“USB 接口”——不管后面接的是数据库、文件系统还是第三方 API，只要遵循 MCP 协议，模型就能统一调用。在 hindsight 项目里，MCP 承担的是记忆读写的通道角色：Agent 通过 MCP 工具调用来查询记忆、写入记忆，而不是把记忆逻辑硬编码在 Agent 内部。

这样做的好处是解耦。记忆系统可以独立部署、独立升级，Agent 侧只需要知道“有个工具能查记忆”就行。而且 MCP 的生态在快速扩张，playwright mcp、burpsuite mcp、blender mcp 这些工具都能通过同一套协议接入，未来扩展很方便。

3.2 记忆读写的 MCP 工具设计

我在项目里定义了三个核心 MCP 工具：memory_query、memory_write、memory_forget。memory_query接收查询文本和过滤条件，返回相关记忆片段；memory_write接收记忆内容和元数据，写入存储；memory_forget用于删除过期或错误的记忆，这个很重要，记忆系统不能只进不出，否则会积累大量噪声。

工具的参数设计有个细节：memory_query我加了top_k和min_score两个参数，前者控制返回条数，后者控制相似度阈值。实测下来，top_k设 5 到 8 比较合适，太多会引入噪声，太少可能漏掉关键信息；min_score根据 embedding 模型不同需要调，我用的模型下 0.75 是个不错的起点。

{ "name": "memory_query", "description": "查询 Agent 历史记忆", "parameters": { "query": "用户偏好的编程语言", "top_k": 5, "min_score": 0.75, "filters": { "user_id": "u_123", "time_range": "last_30_days" } } }

3.3 与 LLM 网关的配合

记忆系统不是孤立的，它要和 LLM 网关配合。网关负责路由请求、管理 token 预算、做限流和降级。我在项目里把记忆检索放在网关的前置阶段：请求进来先查记忆，把相关片段拼进 prompt，再发给模型。这样模型拿到的上下文是经过筛选的，既省 token 又提效果。

这里有个坑要注意：记忆片段拼进 prompt 时，要加明确的分隔标记和来源标注，否则模型可能把记忆内容和当前指令混淆。我用的格式是<memory source="episodic" time="2024-01-15">...</memory>，实测下来模型对这种结构化标记的识别率明显更高。

4. 实操过程：从 Docker 环境到记忆系统跑通

4.1 Docker 环境准备与常见启动问题

整个系统我都是用 Docker 部署的，包括向量库、关系库、MCP 服务、LLM 网关。Windows 环境下装 Docker Desktop 是最省事的，但有几个坑我踩过。第一个是 virtualization support not detected 报错，这个通常是 BIOS 里虚拟化没开，进 BIOS 把 Intel VT-x 或 AMD-V 打开就行。第二个是 WSL2 后端没装，Docker Desktop 启动会卡住，需要先跑wsl --install并重启。

Linux 环境下装 Docker 相对直接，但要注意用户权限，不然后面跑容器会一直要 sudo。我一般会执行这几步：

# 安装 Docker curl -fsSL https://get.docker.com | sh # 把当前用户加入 docker 组 sudo usermod -aG docker $USER # 重新登录使权限生效 newgrp docker # 验证 docker run hello-world

装完之后，我建议先配一个自定义 bridge 网络，后面所有容器都挂到这个网络上，避免默认网络下的通信问题：

docker network create agent-net

4.2 数据库容器的部署与初始化

关系库我用 PostgreSQL，向量库选的是轻量方案。PostgreSQL 的部署命令如下：

docker run -d \ --name pg-memory \ --network agent-net \ -e POSTGRES_PASSWORD=yourpassword \ -e POSTGRES_DB=agent_memory \ -p 5432:5432 \ -v pg_data:/var/lib/postgresql/data \ postgres:16

这里-v pg_data:/var/lib/postgresql/data是关键，把数据卷挂出来，容器删了数据还在。我见过有人不挂卷，结果容器一重建，记忆全没了，哭都来不及。

向量库的部署类似，注意端口不要和 PostgreSQL 冲突。部署完之后，要初始化表结构。我建了三张核心表：episodic_memory存交互片段，semantic_memory存结构化知识，memory_meta存元数据和索引信息。建表 SQL 这里不展开，核心是给user_id、created_at、task_type这几个字段建索引，检索性能差别很大。

4.3 MCP 服务的实现与对接

MCP 服务我用 Python 写的，核心是暴露三个工具接口。服务启动后，要在 Agent 侧配置 MCP 连接。如果你用的是支持 MCP 的 IDE 或客户端，通常在设置里启用“MCP 连接”，然后填入服务地址。我实测下来，本地开发用 stdio 模式最方便，生产环境用 SSE 或 WebSocket 模式。

对接过程中有个常见报错：llm request failed: provider rejected the request schema or tool payload。这个八成是工具的参数 schema 和实际传参不匹配，比如 schema 里定义的是 integer，你传了 string。排查方法很简单，把请求 payload 打出来，逐字段对照 schema 检查。

4.4 记忆抽取流程的落地

抽取流程我单独跑一个容器，定时或事件触发。核心逻辑是：拉取最近的 working memory，跑一遍规则过滤，符合条件的送小模型做结构化抽取，抽取结果写入 episodic 和 semantic 两层。规则过滤这块我列了几个触发条件：包含“我喜欢”“我偏好”“记住”“下次”这类关键词的，包含明确实体和数值的，以及重复出现三次以上的模式。

抽取出来的内容要打分，我用的评分维度包括：信息密度、时效性、复用概率。评分低于阈值的直接丢弃，不写入长期存储。这个阈值需要根据业务调，我一开始设太高，导致记忆太少不够用；后来调低，又引入噪声。最后稳定在 0.6 左右，供你参考。

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

5.1 记忆检索召回不准怎么办

这是最高频的问题。表现是明明存了相关记忆，查询时却召不回来。排查思路分三步：先看 embedding 模型是否合适，不同模型对中文、专业术语的表现差异很大；再看分块策略，记忆片段切得太碎或太长都会影响召回；最后看相似度阈值，设太高会漏，设太低会引入噪声。

我的经验是，记忆片段控制在 200 到 500 字比较合适，太短语义不完整，太长 embedding 会稀释关键信息。另外，查询时可以做一次 query 改写，把用户的口语化表达转成更规范的检索语句，召回率能提升不少。

5.2 Docker 容器间网络不通的排查

容器间网络不通，先确认是否在同一自定义网络下。用docker network inspect agent-net看容器列表，不在里面的说明没挂上。如果在同一网络还通不了，检查容器内的服务是否监听在 0.0.0.0 而不是 127.0.0.1，后者只接受本机连接，容器间访问会失败。

还有一个隐蔽的坑：容器名解析。Docker 自定义网络下可以用容器名当主机名，但如果你用了--link或者默认网络，就得用 IP。我建议统一用自定义网络加容器名，配置清晰，迁移也方便。

5.3 记忆膨胀导致成本失控

记忆只写不删，时间一长存储和检索成本都会飙升。我在项目里加了两个机制：一是 TTL，episodic memory 默认保留 90 天，到期自动归档或删除；二是重要度衰减，长期未被检索到的记忆，重要度评分会随时间下降，低于阈值就清理。

注意：清理策略一定要可配置、可回滚，我见过有人写死删除逻辑，结果误删了关键记忆，没法恢复。建议先归档再删除，保留一个冷存储层。

5.4 常见问题速查表

6. 记忆系统的扩展方向与个人实践体会

跑通基础版本之后，我做了几个扩展，效果不错。一个是记忆的图结构化，把 episodic memory 里的实体和关系抽出来，构建成知识图谱，检索时可以做多跳推理。这个对复杂任务场景帮助很大，比如用户问“上次那个项目的负责人推荐的方案”，需要跨多条记忆关联才能回答。

另一个扩展是记忆的主动遗忘。不是简单按时间删，而是模拟人类的遗忘曲线，高频使用的记忆强化，低频的弱化。实现上就是给每条记忆维护一个激活值，每次检索命中就加，随时间衰减，低于阈值就归档。这个机制让记忆系统更“像人”，也更省资源。

最后分享一个小技巧：记忆系统的调试一定要有可视化。我搭了一个简单的 Web 界面，能看到每条记忆的内容、评分、检索命中记录。没有这个，排查问题基本靠猜。搭起来不复杂，但省下的时间非常可观。

我个人在实际操作中的体会是，Agent 记忆这件事，难的不是技术选型，而是对“什么值得记”的判断。记太多是噪声，记太少不够用，这个平衡点只能在实际业务里反复调。别指望一次调好，留好可配置的接口，边跑边调才是正路。