1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”“hindsight”这个词本身很有意思字面意思是“事后的洞察力”也就是我们常说的“后见之明”。放在AI Agent和LLM的语境里它指向一个非常具体且要命的问题Agent的记忆机制。你肯定遇到过这种情况——跟一个LLM驱动的Agent聊了十几轮它突然忘了你前面说过的关键约束开始胡言乱语或者一个自动化工作流跑了半小时中间某一步的上下文丢了后面全盘崩溃。这不是模型不够聪明而是它的“记忆”没设计好。我最早接触Agent记忆这个概念是在做一套基于MCP协议的多工具编排系统时。当时用Docker把几个服务隔离开每个服务负责不同的工具调用结果发现Agent在跨服务传递上下文时频繁丢状态。后来才意识到LLM本身是无状态的它的“记忆”完全依赖于你每次请求时塞进去的上下文窗口。而hindsight要解决的就是如何让Agent在长周期任务中既能记住该记的又能忘掉该忘的还能在需要的时候把“过去”捞回来。这篇文章适合谁看如果你正在用LLM搭Agent、正在折腾MCP协议的工具接入、或者用Docker部署过带记忆功能的对话系统那下面的内容应该能帮你少踩几个坑。我会从记忆架构的设计思路讲起拆到working memory和长期存储的配合方式再落到Docker环境下的实操部署最后把常见的问题和排查手段整理成速查表。全程按我自己的项目经验来写不堆术语尽量说人话。2. Agent记忆的整体设计与核心思路拆解2.1 为什么LLM的“记忆”不能只靠上下文窗口很多人刚开始做Agent的时候习惯把所有历史对话一股脑塞进prompt里。短对话没问题一旦轮次多了token消耗直线上升而且模型对超长上下文的注意力会衰减——中间部分的信息基本等于没给。我实测过一个20轮的对话把完整历史塞进去模型对第3轮提到的约束条件的召回率不到40%。这不是模型的问题是架构的问题。Agent记忆的核心矛盾在于你需要让Agent知道足够多的过去但又不能让它被过去淹没。hindsight这个思路的本质就是给Agent加一层“记忆管理层”把working memory工作记忆和长期存储分开。工作记忆放当前任务最相关的信息长期存储放历史沉淀需要的时候再检索回来。这跟人脑的工作方式很像——你不会记得昨天午饭吃了什么但如果有人问你“昨天那家餐厅怎么样”你能很快回忆起来。2.2 Working Memory与长期存储的分工逻辑Working memory在Agent里通常表现为一个结构化的短期缓存它保存的是当前会话或当前任务链中最活跃的信息。比如用户刚说的偏好、当前正在处理的文件路径、上一步工具调用的返回值。这部分内容会直接进入每次LLM请求的上下文所以必须精简。长期存储则是另一个极端它可以是向量数据库、关系型数据库、甚至就是文件系统。存进去的东西不会自动出现在prompt里而是通过检索机制按需召回。这里的关键是检索策略——什么时候触发检索、检索多少条、怎么排序。我见过不少项目在这里翻车要么检索太频繁导致上下文被无关信息污染要么检索太少导致Agent“失忆”。一个比较稳的做法是每轮对话结束后用一个轻量级的LLM调用判断当前轮次是否产生了“值得记住”的信息如果有就写入长期存储下一轮开始时用当前query去检索长期存储把top-k条结果注入working memory。这个判断和检索的过程就是hindsight的核心动作。2.3 MCP协议在记忆管理中的角色MCPModel Context Protocol在这里扮演的是“工具接入标准化”的角色。你可以把记忆的读写操作封装成MCP工具比如memory_write、memory_search、memory_forget然后让Agent通过MCP协议来调用。这样做的好处是记忆层和Agent逻辑解耦换一个Agent框架或者换一个LLM记忆层不用重写。我自己的项目里记忆服务是独立跑在一个Docker容器里的通过MCP协议暴露接口。Agent那边只需要配置好MCP server的地址就能像调用普通工具一样操作记忆。这种架构在需要横向扩展的时候特别舒服——记忆服务可以单独扩容Agent节点可以无状态部署。2.4 Docker带来的隔离与可复现性用Docker部署记忆服务最大的好处是环境隔离和可复现。记忆服务通常依赖向量数据库、嵌入模型、缓存中间件这些东西的版本和配置很容易互相打架。Docker compose一写所有依赖锁死换台机器照样跑起来。另外Docker的网络模式对MCP服务很友好。你可以把记忆服务放在一个独立的bridge网络里只暴露MCP端口给Agent容器数据库端口完全不对外。这样即使Agent被注入了恶意指令也没法直接碰到底层存储。3. 核心细节解析与实操要点3.1 记忆写入的触发条件与内容裁剪不是所有对话都值得写入长期记忆。我一开始的做法是每轮都写结果向量库里塞满了“好的”“谢谢”“明白了”这种废话检索的时候噪声极大。后来改成用一个小模型做判断prompt大概是“以下对话轮次是否包含用户偏好、事实性信息、任务约束或重要决策如果是提取关键信息如果不是返回空。”这个判断步骤会增加一次LLM调用但换来的是检索质量的显著提升。实测下来写入量减少了约70%但检索命中率反而提高了。内容裁剪方面我习惯把一轮对话压缩成一条结构化记录包含时间戳、会话ID、关键实体、摘要文本。摘要文本控制在200字以内太长的话嵌入向量的语义会发散。注意写入判断的prompt里一定要明确“不要记录寒暄和确认性回复”否则模型很容易把“好的”也当成重要信息。3.2 检索策略什么时候查、查多少、怎么排检索触发时机一般有两种每轮对话开始前固定检索或者由Agent自己决定是否调用检索工具。前者简单但可能引入无关信息后者灵活但对Agent的规划能力要求高。我目前用的是混合策略每轮开始前做一次轻量检索同时把memory_search作为工具暴露给Agent让它可以在任务中途主动查。检索数量上top-3到top-5是比较舒服的区间。太少可能漏掉关键信息太多会挤占上下文窗口。排序方面除了向量相似度我还会加一个时间衰减因子——越近的记忆权重越高。公式大概是score similarity * 0.7 recency_score * 0.3。recency_score用指数衰减半衰期设成7天左右这样一个月前的记忆权重会降到很低但不会完全消失。3.3 记忆的遗忘机制与冲突处理记忆不是只进不出的。用户改了偏好、任务约束变了、旧信息被证伪了这些情况都需要更新或删除记忆。我的做法是给每条记忆加一个status字段可以是active、superseded、deleted。当新记忆和旧记忆冲突时把旧记忆标记为superseded检索时默认只返回active的。冲突检测可以用LLM来做prompt大概是“以下两条记忆是否矛盾如果矛盾哪条更新”这个判断不需要太精确宁可多标几个superseded也不要让矛盾信息同时出现在上下文里。我踩过的坑是早期没有做冲突处理结果Agent一会儿说“用户喜欢简洁回复”一会儿说“用户要求详细解释”直接精神分裂。3.4 Docker环境下的存储选型与网络配置存储选型上向量检索我用的是Qdrant轻量、Docker镜像小、API简单。关系型元数据用PostgreSQL跟Qdrant配合做混合检索。嵌入模型用的是一个本地部署的小模型通过FastAPI封装成HTTP服务也跑在Docker里。这样整个记忆栈就是三个容器qdrant、postgres、embedding-service再加一个MCP server容器做协议转换。网络配置上我建了一个叫memory-net的bridge网络四个容器都接进去。MCP server暴露一个端口给外部Agent容器其他三个容器的端口只在memory-net内部可见。Docker compose里用expose而不是ports来声明内部端口避免意外暴露到宿主机。services: qdrant: image: qdrant/qdrant:latest networks: - memory-net expose: - 6333 postgres: image: postgres:16 networks: - memory-net expose: - 5432 environment: POSTGRES_PASSWORD: ${PG_PASS} embedding: build: ./embedding networks: - memory-net expose: - 8000 mcp-server: build: ./mcp-server networks: - memory-net ports: - 8080:8080 depends_on: - qdrant - postgres - embedding networks: memory-net: driver: bridge提示PostgreSQL的密码一定要用环境变量注入不要写在compose文件里。我见过有人直接把密码硬编码然后推到公开仓库后果不用多说。4. 实操过程与核心环节实现4.1 从零搭建记忆服务的完整步骤第一步先把目录结构定好。我习惯这样组织memory-stack/ ├── docker-compose.yml ├── embedding/ │ ├── Dockerfile │ └── app.py ├── mcp-server/ │ ├── Dockerfile │ └── server.py └── .env第二步写embedding服务。用FastAPI包一个sentence-transformers模型接口就两个/embed接收文本返回向量/health做健康检查。模型选all-MiniLM-L6-v2384维速度快效果对记忆检索够用。from fastapi import FastAPI from sentence_transformers import SentenceTransformer app FastAPI() model SentenceTransformer(all-MiniLM-L6-v2) app.post(/embed) def embed(texts: list[str]): vectors model.encode(texts, normalize_embeddingsTrue) return {vectors: vectors.tolist()} app.get(/health) def health(): return {status: ok}第三步写MCP server。核心是三个工具memory_write、memory_search、memory_forget。写入时先调embedding服务拿向量然后同时写Qdrant和Postgres。检索时先embed query然后查Qdrant拿top-k再回Postgres补元数据最后按时间衰减重排。from mcp.server import Server from mcp.types import Tool, TextContent import httpx app Server(memory-server) app.list_tools() async def list_tools(): return [ Tool(namememory_write, description写入一条记忆, inputSchema{...}), Tool(namememory_search, description检索相关记忆, inputSchema{...}), Tool(namememory_forget, description标记记忆为失效, inputSchema{...}), ] app.call_tool() async def call_tool(name, arguments): if name memory_write: text arguments[text] vec await embed(text) await qdrant_upsert(vec, arguments) await pg_insert(arguments) return [TextContent(typetext, textwritten)] elif name memory_search: query arguments[query] vec await embed(query) hits await qdrant_search(vec, top_k5) enriched await pg_enrich(hits) ranked recency_rerank(enriched) return [TextContent(typetext, textformat_results(ranked))]第四步docker compose up -d启动。第一次启动时Qdrant和Postgres需要初始化等健康检查通过后再启动mcp-server。compose里的depends_on配合healthcheck可以控制启动顺序。4.2 记忆写入与检索的参数计算嵌入向量的维度是384Qdrant里用Cosine距离。检索时top_k设5但实际注入上下文的只取前3条留2条做缓冲。时间衰减的半衰期我设的是7天计算公式recency_score 0.5 ** (days_ago / 7)比如3天前的记忆recency_score ≈ 0.7414天前的≈ 0.2530天前的≈ 0.05。最终排序分数final_score 0.7 * cosine_similarity 0.3 * recency_score这个权重是我调了几轮之后定下来的。相似度权重太高会导致旧记忆霸屏时间权重太高会让检索变得短视。0.7/0.3在我的场景里比较平衡你可以根据自己的数据分布微调。4.3 Agent侧接入MCP记忆服务的配置Agent侧我用的是一个基于LLM的编排框架配置MCP server的地址就行。关键是要在system prompt里告诉Agent“你可以使用memory_search工具来回忆过去的相关信息使用memory_write来记录重要信息。”同时要在工具调用循环里处理好MCP的返回格式。我实测下来Agent主动调用memory_search的频率并不高大部分时候还是靠每轮开始前的自动检索。但把工具暴露出去有个好处当Agent遇到需要回忆细节的任务时它知道自己有这个能力不会瞎编。4.4 完整链路的联调与验证联调的时候我写了一个简单的测试脚本先写入几条记忆然后模拟几轮对话看检索结果是否符合预期。测试用例包括同义改写查询、时间衰减验证、冲突记忆处理。比如写入“用户喜欢简洁回复”和“用户要求详细解释”两条矛盾记忆看检索时是否只返回最新的那条。验证通过后把整个栈接到实际的Agent工作流里跑一周观察记忆写入量、检索命中率、上下文token消耗。我自己的数据是每天约200轮对话写入约60条记忆检索命中率人工抽检约85%上下文里记忆部分平均占300-500 token完全可以接受。5. 常见问题与排查技巧实录5.1 记忆检索返回无关内容的排查思路最常见的问题是检索出来的记忆跟当前query八竿子打不着。排查顺序先看embedding服务是否正常用相同的文本调两次/embed看向量是否一致再看Qdrant里的collection配置距离度量是不是Cosine维度是不是384然后检查写入时文本是否被截断或污染比如把整个对话历史当成一条记忆写进去了。我遇到过一次检索结果全是“好的”“谢谢”原因是写入判断的prompt没写好模型把确认性回复也标成了重要信息。改prompt之后问题消失。所以写入质量直接决定检索质量这一步不能偷懒。5.2 Docker网络不通的典型场景MCP server连不上Qdrant报Connection refused。先确认两个容器是否在同一个network里docker network inspect memory-net看一眼。然后确认Qdrant的端口是expose还是ports如果是expose宿主机访问不了但同网络容器可以。再检查Qdrant的启动日志有时候是存储卷权限问题导致服务没起来。还有一个坑Docker Desktop在Windows上默认用WSL2后端容器间的DNS解析有时候会抽风。解决办法是在compose里给每个服务加container_name然后用容器名当主机名不要用localhost。5.3 记忆膨胀导致上下文超限的处理跑了一段时间后working memory里注入的记忆越来越多prompt token超了。这时候需要做两件事一是收紧检索的top-k从5降到3二是给working memory设一个token预算比如最多500 token超了就按分数砍掉最低的。另外定期跑一个清理任务把superseded和超过90天没被检索过的active记忆归档。5.4 常见问题速查表问题现象可能原因排查手段解决方式检索结果无关嵌入质量差或写入噪声大检查embedding输出、抽查写入内容优化写入判断prompt、换嵌入模型连接Qdrant失败网络不通或服务未启动docker network inspect、看容器日志确认同网络、检查healthcheck上下文token超限检索条数过多或记忆过长统计prompt token分布降低top-k、压缩记忆文本记忆冲突未做冲突检测抽查检索结果是否矛盾加status字段、LLM冲突判断写入量过大触发条件太宽松统计每日写入条数收紧判断prompt、加去重5.5 几个我踩过的坑和对应技巧第一个坑早期用localhost在compose里配服务地址结果容器内解析不到。后来全部改成服务名问题解决。第二个坑Qdrant的collection没设on_disk数据量大了之后内存爆了。改成on_disk: true之后稳定了。第三个坑embedding服务没做批处理逐条embed延迟很高。改成批量接口后写入吞吐提升了大概5倍。提示如果你用的是Docker Desktop on Windows记得在设置里把WSL2的内存限制调大默认可能只有2GB跑向量数据库很容易OOM。6. 记忆服务的扩展方向与个人体会这套hindsight架构跑了大半年最大的体会是Agent的记忆不是越多越好而是越准越好。我见过太多项目把记忆当成一个“什么都往里塞”的桶结果检索出来的全是噪声Agent反而变得更笨。写入判断、检索排序、冲突处理这三个环节每一个都值得花时间打磨。扩展方向上我最近在试的是分层记忆——把记忆分成“会话级”“任务级”“用户级”三层检索时按层级加权。会话级的记忆权重最高但生命周期最短用户级的记忆权重低但持久。另外记忆的图结构化也是一个有意思的方向把实体和关系抽出来存成图检索时可以做多跳推理。不过这些还在实验阶段等跑稳了再单独写一篇。如果你也在做Agent记忆相关的东西建议先从最简单的向量检索加时间衰减开始跑通了再逐步加复杂度。一上来就搞太复杂的架构调试成本会高到让你想放弃。 Agent记忆架构实战：基于MCP与Docker的hindsight设计
1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”“hindsight”这个词本身很有意思字面意思是“事后的洞察力”也就是我们常说的“后见之明”。放在AI Agent和LLM的语境里它指向一个非常具体且要命的问题Agent的记忆机制。你肯定遇到过这种情况——跟一个LLM驱动的Agent聊了十几轮它突然忘了你前面说过的关键约束开始胡言乱语或者一个自动化工作流跑了半小时中间某一步的上下文丢了后面全盘崩溃。这不是模型不够聪明而是它的“记忆”没设计好。我最早接触Agent记忆这个概念是在做一套基于MCP协议的多工具编排系统时。当时用Docker把几个服务隔离开每个服务负责不同的工具调用结果发现Agent在跨服务传递上下文时频繁丢状态。后来才意识到LLM本身是无状态的它的“记忆”完全依赖于你每次请求时塞进去的上下文窗口。而hindsight要解决的就是如何让Agent在长周期任务中既能记住该记的又能忘掉该忘的还能在需要的时候把“过去”捞回来。这篇文章适合谁看如果你正在用LLM搭Agent、正在折腾MCP协议的工具接入、或者用Docker部署过带记忆功能的对话系统那下面的内容应该能帮你少踩几个坑。我会从记忆架构的设计思路讲起拆到working memory和长期存储的配合方式再落到Docker环境下的实操部署最后把常见的问题和排查手段整理成速查表。全程按我自己的项目经验来写不堆术语尽量说人话。2. Agent记忆的整体设计与核心思路拆解2.1 为什么LLM的“记忆”不能只靠上下文窗口很多人刚开始做Agent的时候习惯把所有历史对话一股脑塞进prompt里。短对话没问题一旦轮次多了token消耗直线上升而且模型对超长上下文的注意力会衰减——中间部分的信息基本等于没给。我实测过一个20轮的对话把完整历史塞进去模型对第3轮提到的约束条件的召回率不到40%。这不是模型的问题是架构的问题。Agent记忆的核心矛盾在于你需要让Agent知道足够多的过去但又不能让它被过去淹没。hindsight这个思路的本质就是给Agent加一层“记忆管理层”把working memory工作记忆和长期存储分开。工作记忆放当前任务最相关的信息长期存储放历史沉淀需要的时候再检索回来。这跟人脑的工作方式很像——你不会记得昨天午饭吃了什么但如果有人问你“昨天那家餐厅怎么样”你能很快回忆起来。2.2 Working Memory与长期存储的分工逻辑Working memory在Agent里通常表现为一个结构化的短期缓存它保存的是当前会话或当前任务链中最活跃的信息。比如用户刚说的偏好、当前正在处理的文件路径、上一步工具调用的返回值。这部分内容会直接进入每次LLM请求的上下文所以必须精简。长期存储则是另一个极端它可以是向量数据库、关系型数据库、甚至就是文件系统。存进去的东西不会自动出现在prompt里而是通过检索机制按需召回。这里的关键是检索策略——什么时候触发检索、检索多少条、怎么排序。我见过不少项目在这里翻车要么检索太频繁导致上下文被无关信息污染要么检索太少导致Agent“失忆”。一个比较稳的做法是每轮对话结束后用一个轻量级的LLM调用判断当前轮次是否产生了“值得记住”的信息如果有就写入长期存储下一轮开始时用当前query去检索长期存储把top-k条结果注入working memory。这个判断和检索的过程就是hindsight的核心动作。2.3 MCP协议在记忆管理中的角色MCPModel Context Protocol在这里扮演的是“工具接入标准化”的角色。你可以把记忆的读写操作封装成MCP工具比如memory_write、memory_search、memory_forget然后让Agent通过MCP协议来调用。这样做的好处是记忆层和Agent逻辑解耦换一个Agent框架或者换一个LLM记忆层不用重写。我自己的项目里记忆服务是独立跑在一个Docker容器里的通过MCP协议暴露接口。Agent那边只需要配置好MCP server的地址就能像调用普通工具一样操作记忆。这种架构在需要横向扩展的时候特别舒服——记忆服务可以单独扩容Agent节点可以无状态部署。2.4 Docker带来的隔离与可复现性用Docker部署记忆服务最大的好处是环境隔离和可复现。记忆服务通常依赖向量数据库、嵌入模型、缓存中间件这些东西的版本和配置很容易互相打架。Docker compose一写所有依赖锁死换台机器照样跑起来。另外Docker的网络模式对MCP服务很友好。你可以把记忆服务放在一个独立的bridge网络里只暴露MCP端口给Agent容器数据库端口完全不对外。这样即使Agent被注入了恶意指令也没法直接碰到底层存储。3. 核心细节解析与实操要点3.1 记忆写入的触发条件与内容裁剪不是所有对话都值得写入长期记忆。我一开始的做法是每轮都写结果向量库里塞满了“好的”“谢谢”“明白了”这种废话检索的时候噪声极大。后来改成用一个小模型做判断prompt大概是“以下对话轮次是否包含用户偏好、事实性信息、任务约束或重要决策如果是提取关键信息如果不是返回空。”这个判断步骤会增加一次LLM调用但换来的是检索质量的显著提升。实测下来写入量减少了约70%但检索命中率反而提高了。内容裁剪方面我习惯把一轮对话压缩成一条结构化记录包含时间戳、会话ID、关键实体、摘要文本。摘要文本控制在200字以内太长的话嵌入向量的语义会发散。注意写入判断的prompt里一定要明确“不要记录寒暄和确认性回复”否则模型很容易把“好的”也当成重要信息。3.2 检索策略什么时候查、查多少、怎么排检索触发时机一般有两种每轮对话开始前固定检索或者由Agent自己决定是否调用检索工具。前者简单但可能引入无关信息后者灵活但对Agent的规划能力要求高。我目前用的是混合策略每轮开始前做一次轻量检索同时把memory_search作为工具暴露给Agent让它可以在任务中途主动查。检索数量上top-3到top-5是比较舒服的区间。太少可能漏掉关键信息太多会挤占上下文窗口。排序方面除了向量相似度我还会加一个时间衰减因子——越近的记忆权重越高。公式大概是score similarity * 0.7 recency_score * 0.3。recency_score用指数衰减半衰期设成7天左右这样一个月前的记忆权重会降到很低但不会完全消失。3.3 记忆的遗忘机制与冲突处理记忆不是只进不出的。用户改了偏好、任务约束变了、旧信息被证伪了这些情况都需要更新或删除记忆。我的做法是给每条记忆加一个status字段可以是active、superseded、deleted。当新记忆和旧记忆冲突时把旧记忆标记为superseded检索时默认只返回active的。冲突检测可以用LLM来做prompt大概是“以下两条记忆是否矛盾如果矛盾哪条更新”这个判断不需要太精确宁可多标几个superseded也不要让矛盾信息同时出现在上下文里。我踩过的坑是早期没有做冲突处理结果Agent一会儿说“用户喜欢简洁回复”一会儿说“用户要求详细解释”直接精神分裂。3.4 Docker环境下的存储选型与网络配置存储选型上向量检索我用的是Qdrant轻量、Docker镜像小、API简单。关系型元数据用PostgreSQL跟Qdrant配合做混合检索。嵌入模型用的是一个本地部署的小模型通过FastAPI封装成HTTP服务也跑在Docker里。这样整个记忆栈就是三个容器qdrant、postgres、embedding-service再加一个MCP server容器做协议转换。网络配置上我建了一个叫memory-net的bridge网络四个容器都接进去。MCP server暴露一个端口给外部Agent容器其他三个容器的端口只在memory-net内部可见。Docker compose里用expose而不是ports来声明内部端口避免意外暴露到宿主机。services: qdrant: image: qdrant/qdrant:latest networks: - memory-net expose: - 6333 postgres: image: postgres:16 networks: - memory-net expose: - 5432 environment: POSTGRES_PASSWORD: ${PG_PASS} embedding: build: ./embedding networks: - memory-net expose: - 8000 mcp-server: build: ./mcp-server networks: - memory-net ports: - 8080:8080 depends_on: - qdrant - postgres - embedding networks: memory-net: driver: bridge提示PostgreSQL的密码一定要用环境变量注入不要写在compose文件里。我见过有人直接把密码硬编码然后推到公开仓库后果不用多说。4. 实操过程与核心环节实现4.1 从零搭建记忆服务的完整步骤第一步先把目录结构定好。我习惯这样组织memory-stack/ ├── docker-compose.yml ├── embedding/ │ ├── Dockerfile │ └── app.py ├── mcp-server/ │ ├── Dockerfile │ └── server.py └── .env第二步写embedding服务。用FastAPI包一个sentence-transformers模型接口就两个/embed接收文本返回向量/health做健康检查。模型选all-MiniLM-L6-v2384维速度快效果对记忆检索够用。from fastapi import FastAPI from sentence_transformers import SentenceTransformer app FastAPI() model SentenceTransformer(all-MiniLM-L6-v2) app.post(/embed) def embed(texts: list[str]): vectors model.encode(texts, normalize_embeddingsTrue) return {vectors: vectors.tolist()} app.get(/health) def health(): return {status: ok}第三步写MCP server。核心是三个工具memory_write、memory_search、memory_forget。写入时先调embedding服务拿向量然后同时写Qdrant和Postgres。检索时先embed query然后查Qdrant拿top-k再回Postgres补元数据最后按时间衰减重排。from mcp.server import Server from mcp.types import Tool, TextContent import httpx app Server(memory-server) app.list_tools() async def list_tools(): return [ Tool(namememory_write, description写入一条记忆, inputSchema{...}), Tool(namememory_search, description检索相关记忆, inputSchema{...}), Tool(namememory_forget, description标记记忆为失效, inputSchema{...}), ] app.call_tool() async def call_tool(name, arguments): if name memory_write: text arguments[text] vec await embed(text) await qdrant_upsert(vec, arguments) await pg_insert(arguments) return [TextContent(typetext, textwritten)] elif name memory_search: query arguments[query] vec await embed(query) hits await qdrant_search(vec, top_k5) enriched await pg_enrich(hits) ranked recency_rerank(enriched) return [TextContent(typetext, textformat_results(ranked))]第四步docker compose up -d启动。第一次启动时Qdrant和Postgres需要初始化等健康检查通过后再启动mcp-server。compose里的depends_on配合healthcheck可以控制启动顺序。4.2 记忆写入与检索的参数计算嵌入向量的维度是384Qdrant里用Cosine距离。检索时top_k设5但实际注入上下文的只取前3条留2条做缓冲。时间衰减的半衰期我设的是7天计算公式recency_score 0.5 ** (days_ago / 7)比如3天前的记忆recency_score ≈ 0.7414天前的≈ 0.2530天前的≈ 0.05。最终排序分数final_score 0.7 * cosine_similarity 0.3 * recency_score这个权重是我调了几轮之后定下来的。相似度权重太高会导致旧记忆霸屏时间权重太高会让检索变得短视。0.7/0.3在我的场景里比较平衡你可以根据自己的数据分布微调。4.3 Agent侧接入MCP记忆服务的配置Agent侧我用的是一个基于LLM的编排框架配置MCP server的地址就行。关键是要在system prompt里告诉Agent“你可以使用memory_search工具来回忆过去的相关信息使用memory_write来记录重要信息。”同时要在工具调用循环里处理好MCP的返回格式。我实测下来Agent主动调用memory_search的频率并不高大部分时候还是靠每轮开始前的自动检索。但把工具暴露出去有个好处当Agent遇到需要回忆细节的任务时它知道自己有这个能力不会瞎编。4.4 完整链路的联调与验证联调的时候我写了一个简单的测试脚本先写入几条记忆然后模拟几轮对话看检索结果是否符合预期。测试用例包括同义改写查询、时间衰减验证、冲突记忆处理。比如写入“用户喜欢简洁回复”和“用户要求详细解释”两条矛盾记忆看检索时是否只返回最新的那条。验证通过后把整个栈接到实际的Agent工作流里跑一周观察记忆写入量、检索命中率、上下文token消耗。我自己的数据是每天约200轮对话写入约60条记忆检索命中率人工抽检约85%上下文里记忆部分平均占300-500 token完全可以接受。5. 常见问题与排查技巧实录5.1 记忆检索返回无关内容的排查思路最常见的问题是检索出来的记忆跟当前query八竿子打不着。排查顺序先看embedding服务是否正常用相同的文本调两次/embed看向量是否一致再看Qdrant里的collection配置距离度量是不是Cosine维度是不是384然后检查写入时文本是否被截断或污染比如把整个对话历史当成一条记忆写进去了。我遇到过一次检索结果全是“好的”“谢谢”原因是写入判断的prompt没写好模型把确认性回复也标成了重要信息。改prompt之后问题消失。所以写入质量直接决定检索质量这一步不能偷懒。5.2 Docker网络不通的典型场景MCP server连不上Qdrant报Connection refused。先确认两个容器是否在同一个network里docker network inspect memory-net看一眼。然后确认Qdrant的端口是expose还是ports如果是expose宿主机访问不了但同网络容器可以。再检查Qdrant的启动日志有时候是存储卷权限问题导致服务没起来。还有一个坑Docker Desktop在Windows上默认用WSL2后端容器间的DNS解析有时候会抽风。解决办法是在compose里给每个服务加container_name然后用容器名当主机名不要用localhost。5.3 记忆膨胀导致上下文超限的处理跑了一段时间后working memory里注入的记忆越来越多prompt token超了。这时候需要做两件事一是收紧检索的top-k从5降到3二是给working memory设一个token预算比如最多500 token超了就按分数砍掉最低的。另外定期跑一个清理任务把superseded和超过90天没被检索过的active记忆归档。5.4 常见问题速查表问题现象可能原因排查手段解决方式检索结果无关嵌入质量差或写入噪声大检查embedding输出、抽查写入内容优化写入判断prompt、换嵌入模型连接Qdrant失败网络不通或服务未启动docker network inspect、看容器日志确认同网络、检查healthcheck上下文token超限检索条数过多或记忆过长统计prompt token分布降低top-k、压缩记忆文本记忆冲突未做冲突检测抽查检索结果是否矛盾加status字段、LLM冲突判断写入量过大触发条件太宽松统计每日写入条数收紧判断prompt、加去重5.5 几个我踩过的坑和对应技巧第一个坑早期用localhost在compose里配服务地址结果容器内解析不到。后来全部改成服务名问题解决。第二个坑Qdrant的collection没设on_disk数据量大了之后内存爆了。改成on_disk: true之后稳定了。第三个坑embedding服务没做批处理逐条embed延迟很高。改成批量接口后写入吞吐提升了大概5倍。提示如果你用的是Docker Desktop on Windows记得在设置里把WSL2的内存限制调大默认可能只有2GB跑向量数据库很容易OOM。6. 记忆服务的扩展方向与个人体会这套hindsight架构跑了大半年最大的体会是Agent的记忆不是越多越好而是越准越好。我见过太多项目把记忆当成一个“什么都往里塞”的桶结果检索出来的全是噪声Agent反而变得更笨。写入判断、检索排序、冲突处理这三个环节每一个都值得花时间打磨。扩展方向上我最近在试的是分层记忆——把记忆分成“会话级”“任务级”“用户级”三层检索时按层级加权。会话级的记忆权重最高但生命周期最短用户级的记忆权重低但持久。另外记忆的图结构化也是一个有意思的方向把实体和关系抽出来存成图检索时可以做多跳推理。不过这些还在实验阶段等跑稳了再单独写一篇。如果你也在做Agent记忆相关的东西建议先从最简单的向量检索加时间衰减开始跑通了再逐步加复杂度。一上来就搞太复杂的架构调试成本会高到让你想放弃。