Agent记忆系统实战：基于MCP与Docker的hindsight架构设计

1. 从“hindsight”说起：为什么我们需要给Agent装上“后视镜”

第一次看到“hindsight”这个词，是在做一个多轮对话Agent的复盘工具时。当时团队里有个争论：Agent到底需不需要“记住”上一次任务失败的原因？有人觉得每次请求都是独立的，上下文窗口塞进去就够了；有人坚持认为，没有跨会话记忆的Agent，永远只能当个“金鱼脑”助手。后来我们做了一版带记忆回溯的Agent，效果提升非常明显——它开始能说出“上次你让我查的那个接口，这次我换了个方式重试成功了”这种话。这就是hindsight的价值：它不是让Agent变聪明，而是让Agent变得“有经验”。

hindsight这个词本身是“事后之明”的意思，放在Agent memory这个领域里，它指的是一套让LLM-based Agent能够回溯、检索、利用历史交互记录来优化当前决策的机制。你可以把它理解成给Agent装了一个“后视镜”——不是用来往前看的，而是用来在变道、超车之前，确认一下后面有没有来车。在Agent执行任务的过程中，hindsight负责把过去的成功路径、失败教训、用户偏好、环境状态都存下来，等到类似场景再次出现时，自动把相关记忆注入到当前上下文中。

这套东西解决的核心问题是：LLM的上下文窗口是有限的，但Agent需要处理的任务历史是无限的。你不能把所有历史对话都塞进prompt里，那样token成本会爆炸，而且模型注意力会被稀释。hindsight的思路是，把历史记忆做结构化存储和按需检索，只在需要的时候把最相关的片段拉出来。这跟RAG的思路有点像，但RAG检索的是外部知识库，hindsight检索的是Agent自己的“经历”。

适合读这篇内容的人，大概分三类：一是正在做Agent产品的开发者，尤其是那些发现Agent“记性不好”导致用户体验断层的；二是对LLM应用架构感兴趣的技术人，想了解memory模块怎么设计；三是已经在用MCP协议搭工具链的工程师，因为hindsight和MCP的配合是一个很自然的组合。不管你是哪一类，接下来的内容会从设计思路、核心细节、实操落地到问题排查，把hindsight这套东西拆开讲清楚。

2. 整体设计思路：hindsight为什么不能做成简单的“聊天记录数据库”

2.1 核心矛盾：记忆的“全量存储”与“精准召回”

很多人第一次做Agent memory的时候，直觉反应是：把每轮对话都存进数据库，下次用的时候按时间倒序取最近N条不就行了？这个方案在demo阶段能跑通，但一上生产就崩。原因有两个：第一，最近N条不一定相关。用户上周问过“帮我订会议室”，今天问“帮我订机票”，你把订会议室的记录塞进去，模型会困惑。第二，全量存储的检索效率会随着数据量增长而急剧下降，你不可能每次请求都去扫一遍几万条记录。

hindsight的设计核心是“分层记忆+按需召回”。它把Agent的记忆分成几个层次：工作记忆（working memory）是当前会话的上下文，短期记忆（short-term memory）是最近几次会话的摘要，长期记忆（long-term memory）是经过压缩和索引的历史经验。每一层有不同的存储介质、不同的检索策略、不同的过期规则。这个分层思路借鉴了认知科学里的人类记忆模型，但在工程上做了简化，保证可落地。

提示：不要一上来就追求“完美记忆”。先做工作记忆和短期记忆，长期记忆可以后面再补。很多场景下，Agent只需要记住最近3-5次交互的关键信息，效果就已经比“金鱼脑”好很多了。

2.2 为什么选择MCP作为记忆暴露的接口

MCP（Model Context Protocol）在这套架构里扮演的是“记忆访问层”的角色。你可能会问：为什么不直接在Agent代码里调用数据库，非要绕一层MCP？我的考虑是解耦和复用。Agent的逻辑代码不应该关心记忆存在哪里、怎么检索，它只需要知道“我有一个记忆工具可以调用”。MCP把记忆的读写封装成标准化的工具接口，Agent通过MCP client来调用，这样换存储后端、换检索算法，都不需要动Agent的核心逻辑。

另外，MCP的另一个好处是跨Agent共享记忆。如果你有多个Agent在同一个环境里工作，它们可以通过同一个MCP server来读写共享记忆。比如一个客服Agent和一个工单Agent，客服Agent记录的用户问题，工单Agent可以直接检索到，不需要通过人工转述。这种共享能力在单机代码里实现起来很麻烦，但用MCP就自然很多。

2.3 Docker在其中的角色：环境一致性与快速迭代

Docker在这套方案里不是必须的，但用了之后会省很多事。hindsight涉及多个组件：LLM调用、向量数据库、MCP server、Agent运行时。如果每个组件都手动装环境，光是版本兼容就能折腾一天。用Docker Compose把整个栈编排起来，一条命令启动，环境一致性有保障，换机器也能快速复现。

我自己的做法是，把MCP server和向量数据库放在同一个Docker网络里，Agent运行时通过服务名访问，不暴露外部端口。这样既安全，又避免了“docker网络不通”这类常见问题。后面在实操部分会详细讲这个编排文件怎么写。

3. 核心细节解析：hindsight的记忆结构、检索策略与Token控制

3.1 记忆的三种类型：Key、Query、Value的重新理解

在hindsight里，我把每条记忆抽象成三个部分：Key、Query、Value。这个命名可能跟你在别的地方看到的不太一样，我解释一下我的用法。

Key是“我是谁”——也就是这条记忆属于哪个Agent、哪个用户、哪个会话。它解决的是隔离问题。没有Key，多个用户的记忆会混在一起，检索出来的东西张冠李戴。Query是“我在找什么”——也就是检索时用的查询向量或关键词。Value是“我能提供什么”——也就是记忆的实际内容，可能是一段文本、一个结构化JSON、或者一个工具调用记录。

这个三元组的设计灵感来自一个很朴素的观察：Agent在回忆的时候，先要知道“这是谁的事”，再要知道“我要找什么类型的事”，最后才是“具体是什么事”。很多memory方案只做了Query和Value，忽略了Key，结果在多用户场景下就出问题。

3.2 检索策略：向量检索+关键词过滤+时间衰减

hindsight的检索不是单纯的向量相似度排序。我实测下来，纯向量检索在记忆场景下有几个坑：第一，语义相似的记忆可能时间上差很远，用户已经改过需求了，你还把旧记忆排在前面；第二，有些记忆是靠关键词精确匹配的，比如订单号、用户ID，向量检索反而会漏掉。

所以我的策略是三层过滤：先用Key做硬过滤，把不属于当前用户/Agent的记忆排除；再用关键词做精确匹配，把包含特定实体（如订单号、产品名）的记忆捞出来；最后用向量相似度做语义排序，同时叠加一个时间衰减因子——越新的记忆权重越高，但不会完全覆盖旧记忆。时间衰减的公式我用的是指数衰减：weight = similarity * exp(-lambda * age_in_days)，lambda取0.1左右，意味着7天前的记忆权重会降到大约一半。

这个公式不是拍脑袋来的。我试过线性衰减和阶梯衰减，线性衰减在age比较大的时候权重下降太慢，导致旧记忆干扰；阶梯衰减又太粗暴，容易把有用的旧记忆一刀切掉。指数衰减比较符合直觉：最近几天的记忆很重要，几周前的记忆还有参考价值，几个月前的记忆基本只剩“教训”层面的价值了。

3.3 Token预算控制：记忆注入不能挤占任务指令

这是很多开发者容易忽略的一点：你把记忆检索出来之后，怎么塞进prompt？如果塞太多，任务指令的token预算就被挤占了，模型可能连“你要干什么”都忘了。我的做法是给记忆注入设一个硬上限，比如总prompt的30%。如果检索出来的记忆超过这个上限，就按权重截断，只保留top-K条。

另外，记忆的呈现格式也很重要。我试过直接把原始对话记录贴进去，模型理解起来很费劲。后来改成结构化格式：每条记忆用一行摘要+关键字段的方式呈现，比如[2024-01-15] 用户询问退款政策，Agent回复需提供订单号，用户提供了订单号XXX，退款成功。这种格式比原始对话省token，而且模型更容易抓重点。

注意：记忆注入的位置也会影响效果。我习惯把记忆放在system prompt之后、用户当前query之前。放在最后面模型容易忽略，放在最前面又可能干扰角色设定。

4. 实操过程：从零搭建一个带hindsight的Agent记忆系统

4.1 环境准备：Docker Compose编排MCP Server与向量库

先上编排文件。我用的是Qdrant作为向量存储，因为它轻量、API简单、Docker镜像小。MCP server用Python写，基于官方SDK。Agent运行时我用的是自己写的一个轻量循环，你也可以换成任何支持MCP client的框架。

version: "3.8" services: qdrant: image: qdrant/qdrant:latest ports: - "6333:6333" volumes: - ./qdrant_data:/qdrant/storage networks: - agent-net hindsight-mcp: build: ./hindsight-mcp environment: - QDRANT_HOST=qdrant - QDRANT_PORT=6333 - EMBEDDING_MODEL=text-embedding-3-small - OPENAI_API_KEY=${OPENAI_API_KEY} depends_on: - qdrant networks: - agent-net networks: agent-net: driver: bridge

这个编排文件里，qdrant和hindsight-mcp在同一个bridge网络里，MCP server通过服务名qdrant访问向量库，不需要暴露6333到宿主机。如果你在Windows上跑Docker Desktop，记得在设置里确认虚拟化支持已开启，否则会报“virtualization support not detected”然后启动失败。Mac用户一般没这个问题，Linux用户需要确认内核模块加载正常。

4.2 MCP Server的核心实现：记忆写入与检索

MCP server我实现了两个工具：memory_write和memory_search。写入的时候，把Key、Query、Value分别处理：Key存成payload的字段用于过滤，Query做embedding后存向量，Value存原始内容。检索的时候，先按Key过滤，再按向量相似度排序，最后叠加时间衰减。

from mcp.server import Server from mcp.types import Tool, TextContent import qdrant_client from qdrant_client.models import PointStruct, Filter, FieldCondition, MatchValue import openai import time import math app = Server("hindsight-mcp") client = qdrant_client.QdrantClient(host="qdrant", port=6333) COLLECTION = "agent_memory" @app.tool() async def memory_write(agent_id: str, user_id: str, content: str, memory_type: str = "episodic"): embedding = openai.embeddings.create( model="text-embedding-3-small", input=content ).data[0].embedding point = PointStruct( id=str(uuid.uuid4()), vector=embedding, payload={ "agent_id": agent_id, "user_id": user_id, "content": content, "memory_type": memory_type, "timestamp": time.time() } ) client.upsert(collection_name=COLLECTION, points=[point]) return TextContent(type="text", text="memory written") @app.tool() async def memory_search(agent_id: str, user_id: str, query: str, top_k: int = 5): query_vec = openai.embeddings.create( model="text-embedding-3-small", input=query ).data[0].embedding results = client.search( collection_name=COLLECTION, query_vector=query_vec, query_filter=Filter( must=[ FieldCondition(key="agent_id", match=MatchValue(value=agent_id)), FieldCondition(key="user_id", match=MatchValue(value=user_id)) ] ), limit=top_k * 2 ) now = time.time() scored = [] for r in results: age_days = (now - r.payload["timestamp"]) / 86400 decay = math.exp(-0.1 * age_days) scored.append((r.score * decay, r.payload["content"])) scored.sort(reverse=True) top = scored[:top_k] return TextContent(type="text", text="\n".join([f"[{s:.3f}] {c}" for s, c in top]))

这段代码里，memory_search先取top_k*2的结果，再用时间衰减重新排序，最后截取top_k。为什么要多取一倍？因为衰减之后排序可能变化，多取一些保证最终结果的质量。这个细节在文档里不会写，但实测下来对召回质量有肉眼可见的提升。

4.3 Agent侧的集成：把记忆注入prompt

Agent侧的逻辑很简单：在每次调用LLM之前，先用当前query去memory_search，把返回的记忆拼成一段文本，插入到system prompt和用户消息之间。任务结束后，把关键信息用memory_write存回去。

async def run_agent_turn(agent_id, user_id, user_message): memories = await mcp_client.call_tool( "memory_search", {"agent_id": agent_id, "user_id": user_id, "query": user_message, "top_k": 5} ) memory_text = memories.content[0].text if memories.content else "无相关记忆" system_prompt = f"""你是一个有帮助的助手。 以下是你过去与这位用户的交互记忆，供参考： {memory_text} """ response = await llm.chat(system_prompt, user_message) await mcp_client.call_tool( "memory_write", { "agent_id": agent_id, "user_id": user_id, "content": f"用户说：{user_message}；助手回复：{response[:200]}" } ) return response

这里有个细节：写入记忆的时候，我没有存完整的回复，而是截取了前200个字符。原因是完整回复可能很长，存进去会浪费存储和检索时的token。200个字符足够概括这次交互的核心内容了。如果你需要存完整回复，建议单独存一个字段，检索时只返回摘要。

4.4 参数选择与计算过程

时间衰减的lambda我取了0.1，这个值是怎么来的？我做了几组对比实验：lambda=0.05时，30天前的记忆权重还有0.22，干扰比较明显；lambda=0.2时，7天前的记忆权重就降到0.25了，衰减太快，一些有用的中期记忆被埋没。0.1是一个平衡点，7天权重约0.5，30天权重约0.05，符合“近期记忆优先，远期记忆仅作参考”的直觉。

top_k我默认取5，这个数字也不是随便定的。我试过3、5、10三个值：3条的时候，有时候关键记忆没被召回；10条的时候，prompt里记忆部分太长，模型开始忽略任务指令。5条是一个比较稳妥的默认值，你可以根据自己场景的prompt预算调整。

embedding模型我用的text-embedding-3-small，1536维。为什么不用large？因为记忆检索对精度的要求没有知识库问答那么高，small模型够用，而且成本低、速度快。如果你对召回精度要求极高，可以换large，但token成本会上去。

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

5.1 记忆检索不相关：先查Key过滤，再查embedding质量

最常见的问题就是检索出来的记忆跟当前query不相关。排查顺序是这样的：第一步，确认Key过滤是否正确。我遇到过agent_id传错的情况，导致检索到了别的Agent的记忆。第二步，检查embedding模型是否一致。写入和检索必须用同一个模型，否则向量空间不对齐，相似度计算完全没意义。第三步，看query本身是否太短或太模糊。如果用户只说“好的”，那检索出什么都有可能，这时候可以考虑用上一轮的用户消息作为query。

提示：可以在memory_search里加一个score阈值，低于阈值的记忆直接丢弃。我一般设0.3左右，低于这个值的记忆基本是噪声。

5.2 Docker网络不通：检查服务名和网络配置

“docker网络不通”是高频问题。如果你的MCP server连不上Qdrant，先确认两点：一是两个服务是否在同一个network里，二是连接时用的是服务名还是localhost。在Docker Compose里，服务之间用服务名互相访问，用localhost会指向容器自己，当然连不上。另外，如果你在MCP server里硬编码了localhost:6333，改成qdrant:6333就好了。

还有一个坑是Qdrant的启动顺序。虽然我写了depends_on，但那只保证容器启动顺序，不保证Qdrant已经准备好接受连接。稳妥的做法是在MCP server里加一个重试逻辑，连不上就等几秒再试。

5.3 Token超限：记忆注入的预算控制

如果你发现LLM报token超限，大概率是记忆注入太多了。检查一下memory_search返回的条数和每条的长度。我建议在MCP server里就做截断，每条记忆最多500字符，总返回不超过2000字符。这样Agent侧不用再处理截断逻辑，prompt预算也可控。

另外，如果你的任务指令本身就很长，可以考虑把记忆压缩成更短的摘要。比如用一个小模型先把记忆摘要成一句话，再注入。这个方案会增加一次LLM调用，但能显著降低token消耗。

5.4 记忆写入重复：去重策略

同一个信息被多次写入是常见问题。比如用户每次都说“我的订单号是XXX”，你每次都存一条，检索时全是重复的。我的做法是在写入前先做一次相似度检查，如果跟最近N条记忆的相似度超过0.95，就跳过写入，或者更新已有记忆的时间戳。

这个去重逻辑可以放在MCP server的memory_write里，也可以放在Agent侧。我倾向于放在MCP server里，因为这样所有Agent共享同一套去重规则，不会因为Agent实现不同而行为不一致。

5.5 一个容易被忽略的坑：记忆的“污染”

最后说一个比较隐蔽的问题：记忆污染。如果Agent某次回复是错的，你把这段错误交互存进了记忆，下次检索出来，模型会以为那是正确的历史，继续沿着错误路径走。这个问题在长期运行的Agent里特别危险。

我的应对策略是给记忆加一个“可信度”字段。Agent自己生成的回复，可信度标记为medium；用户明确确认过的信息，可信度标记为high；未经确认的推测，可信度标记为low。检索时，high可信度的记忆权重乘以1.5，low的乘以0.5。这样即使有错误记忆，也不会主导检索结果。

另外，定期做记忆清理也很重要。我一般每周跑一次清理任务，把30天以上、从未被检索过的记忆归档或删除。这些记忆大概率是噪声，留着只会增加检索负担。

6. 记忆系统的扩展方向：从hindsight到更完整的Agent记忆架构

hindsight这套东西跑通之后，你会发现它只是一个起点。真正完整的Agent记忆架构还需要考虑几个扩展方向。第一个是程序性记忆（procedural memory），也就是Agent学会的“技能”——比如某个API的调用方式、某个工具的参数格式。这类记忆跟情景记忆不同，它更稳定、更结构化，适合用单独的存储和检索策略。第二个是记忆的主动遗忘机制，不是所有记忆都值得保留，有些记忆过期了就应该被清理，否则会干扰新记忆的检索。第三个是跨Agent的记忆共享与权限控制，多个Agent共享记忆池的时候，怎么保证A Agent不能读到B Agent的私有记忆，这是一个需要认真设计的问题。

我目前在做的实验是把hindsight和GraphRAG结合起来，用图结构来表示记忆之间的关联。比如“用户A”和“订单B”和“退款事件C”之间有关系，检索的时候可以沿着图遍历，把相关记忆一起拉出来。这个方案还在早期阶段，效果有待验证，但方向我觉得是对的。记忆不是孤立的点，而是有结构的网，这一点在复杂任务场景下会越来越明显。

如果你也在做Agent memory相关的东西，我的建议是先从最简单的分层记忆做起，把工作记忆和短期记忆跑通，再逐步加长期记忆和检索优化。不要一上来就追求大而全的架构，那样很容易在细节里迷失。hindsight的核心价值不在于技术多复杂，而在于它让Agent从“每次都是第一次”变成“有经验可循”，这个转变带来的体验提升，比任何花哨的架构都实在。