1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词是在一个做LLM Agent的朋友群里。有人丢了一张截图说他们的Agent在连续对话到第37轮的时候突然把用户三小时前说过的偏好设置忘得一干二净回复开始胡言乱语。底下有人回了一句“这不就是典型的没有hindsight吗——它只能看见眼前看不见身后。”这个词翻译过来叫“后见之明”但在Agent memory的语境里它指的是一套让LLM Agent能够回溯、检索、利用历史交互信息的记忆机制。你可以把它理解成给Agent装了一面后视镜它不改变车往哪开但能让驾驶者知道刚才经过了什么、有没有漏掉该拐的路口。我接触Agent memory这个方向大概有一年多时间从最早的简单滑动窗口到后来的向量数据库检索再到最近结合MCP协议做跨会话记忆持久化踩过的坑比写过的代码还多。这篇文章想聊的就是围绕“hindsight”这个核心概念把Agent memory从设计思路到落地实操的完整链路拆开来讲。不管你是刚接触LLM应用开发的新手还是已经在做多轮对话系统的老手应该都能从里面找到一些可以直接抄作业的东西。先明确一下这篇文章要解决的问题域当一个LLM Agent需要记住用户说过的话、做过的操作、形成的偏好并且在后续对话中准确调用这些信息时它的记忆系统应该怎么设计存储层用什么检索策略怎么定MCP协议在这里扮演什么角色Docker部署时有哪些坑这些都是实打实要面对的问题。2. Agent memory的核心设计思路拆解2.1 为什么滑动窗口不够用从“失忆”说起大部分LLM应用最开始都是靠上下文窗口硬扛。用户问一句模型答一句把最近N轮对话拼成prompt塞进去。这种做法在短对话里没问题但一旦对话轮次超过二三十轮就会遇到两个硬瓶颈。第一个瓶颈是token成本。假设每轮对话平均200个token30轮就是6000个token再加上系统提示词和工具描述轻松破万。如果每轮都全量携带API调用成本会线性增长响应延迟也会肉眼可见地变慢。第二个瓶颈更致命即使你愿意花钱把全部历史塞进去模型对长上下文的注意力分配也是不均匀的。大量实验表明LLM对上下文中间部分的信息召回率明显低于开头和结尾这就是所谓的“lost in the middle”现象。所以Agent memory要解决的核心问题不是“能不能存”而是“存什么、怎么取、什么时候取”。hindsight这个概念的价值就在于它强调的是一种主动回溯的能力——不是被动地把所有历史都塞给模型而是让Agent在需要的时候能够精准地“回头看”。2.2 三层记忆架构working memory、episodic memory、semantic memory参考认知科学里对人类记忆的分类我在实际项目中通常把Agent memory分成三层。Working memory对应的是当前会话的短期上下文生命周期就是一次会话。它存储的是最近几轮对话的原始文本通常用滑动窗口加摘要的方式管理。当窗口满了就把最老的那部分对话压缩成一段摘要保留关键信息丢弃冗余表达。Episodic memory对应的是跨会话的事件记忆。比如用户上周三说过“我下个月要搬家”这条信息在当前会话结束后不应该消失而应该被持久化下来等到用户下次提到搬家相关话题时能够被检索出来。这一层通常用向量数据库存储每条记忆是一个独立的embedding向量附带时间戳和元数据。Semantic memory对应的是从多次交互中抽象出来的规律性知识。比如Agent通过多次对话发现某个用户总是偏好简洁的回答风格这个“偏好简洁”就是一个semantic memory。它不依赖于某一次具体交互而是从episodic memory中归纳出来的。这三层不是孤立的而是有明确的读写路径。Working memory在会话结束时由LLM判断哪些信息值得写入episodic memoryepisodic memory积累到一定量后再通过聚类或摘要生成semantic memory。检索时优先查working memory不够再查episodic最后查semantic。2.3 为什么选MCP而不是自己写一套APIMCPModel Context Protocol在这套架构里的角色是标准化Agent与外部记忆存储之间的通信接口。在没有MCP之前每个Agent框架都有自己的工具调用格式OpenAI的function calling、Anthropic的tool use、LangChain的Tool接口各不相同。你要换一个LLM提供商记忆模块的对接代码就得重写一遍。MCP把这个过程标准化了。它定义了一套基于JSON-RPC的协议Agent通过MCP Server暴露记忆读写能力LLM通过MCP Client调用这些能力。好处是解耦记忆存储的实现可以独立演进只要MCP接口不变上层Agent就不用改代码。而且MCP天然支持流式传输和双向通信对于需要实时写入记忆的场景很友好。我实测下来用MCP做记忆层抽象切换底层存储从Redis到Postgres到Qdrant的时间从原来的两三天缩短到半天以内。这个收益在快速迭代阶段非常明显。3. 核心细节解析与实操要点3.1 记忆写入策略什么时候该记什么时候该忘这是整个系统里最难调的部分。记太多检索时噪声大模型容易被无关信息干扰记太少关键信息丢失Agent显得“没记性”。我的经验是采用“LLM打分规则过滤”的双层策略。每轮对话结束后把用户输入和Agent回复一起送给一个轻量级LLM比如7B级别的模型让它从三个维度打分信息密度、时效性、可复用性。三个维度加权求和超过阈值的才写入episodic memory。具体打分prompt可以这样设计MEMORY_SCORING_PROMPT 你是一个记忆重要性评估器。请对以下对话片段进行打分每个维度1-5分。 对话内容 用户{user_input} 助手{assistant_response} 评分维度 1. 信息密度是否包含具体的事实、偏好、计划或约束条件 2. 时效性这条信息是否在近期内可能被再次提及 3. 可复用性这条信息是否适用于未来的多次交互 请以JSON格式输出{{density: score, timeliness: score, reusability: score}} 阈值设定上我一般取加权平均3.5分。低于这个分数的对话片段直接丢弃不进入长期记忆。这个阈值可以根据业务场景调整客服场景可以调低到3.0因为用户说的每句话可能都有用闲聊场景可以调高到4.0避免存储大量无意义寒暄。注意打分模型和主对话模型最好分开。用同一个大模型既做对话又做记忆评估会导致token消耗翻倍而且评估结果容易受对话上下文干扰。用一个小的、专门的模型做评估成本更低判断也更稳定。3.2 记忆检索向量相似度不是万能的很多人一提到记忆检索就想到向量数据库觉得把记忆embedding存进去查询时算余弦相似度就完事了。实际用下来纯向量检索有三个明显问题。第一时间衰减被忽略。三个月前的一条记忆和昨天的一条记忆如果向量相似度差不多应该优先返回哪条显然是最近的。所以检索分数里必须加入时间衰减因子。我通常用指数衰减score similarity * exp(-λ * days_ago)λ取0.01到0.05之间具体看业务对时效性的敏感程度。第二关键词匹配仍然重要。用户说“帮我订上次那家餐厅”向量检索可能返回一堆餐厅相关的记忆但“上次”这个时间指示词需要结合时间戳过滤才能准确定位。所以我在检索时会同时跑一路BM25关键词检索然后把两路结果做融合排序。第三检索数量要控制。返回太多记忆会挤占上下文窗口返回太少可能漏掉关键信息。我的经验值是top-5到top-8之间具体取决于单条记忆的平均长度。如果单条记忆超过200token就取top-5如果比较短可以取top-8。3.3 MCP Server的实现要点用MCP协议暴露记忆能力需要实现几个核心工具toolmemory_write写入一条新记忆参数包括内容、类型episodic/semantic、元数据memory_search根据查询文本检索相关记忆参数包括查询、top_k、时间范围memory_forget删除指定记忆用于用户主动要求“忘记”的场景memory_summarize对一段时间范围内的记忆做摘要用于生成semantic memoryMCP Server的实现可以用Python的mcp库也可以用TypeScript的modelcontextprotocol/sdk。我两种都用过Python版在数据处理生态上更顺手TypeScript版在流式传输和并发处理上更自然。如果记忆存储用的是向量数据库Python版可以直接调用qdrant-client或chromadb代码量更少。一个容易踩的坑是MCP Server的启动方式。如果你用Docker部署MCP Server需要以stdio或SSE模式运行。stdio模式适合本地开发Agent和Server在同一台机器上SSE模式适合远程部署Agent通过HTTP连接到Server。我建议开发阶段用stdio生产环境用SSE因为SSE支持多客户端并发连接而且更容易做鉴权和限流。4. 实操过程与核心环节实现4.1 环境准备Docker与依赖安装整套系统的部署我推荐用Docker Compose编排把MCP Server、向量数据库、Redis做working memory缓存放在同一个网络里。这样Agent只需要连接MCP Server的端口不需要关心底层存储的具体地址。先装Docker Desktop。Windows用户注意安装过程中如果提示“Virtualization support not detected”需要进BIOS开启CPU虚拟化Intel VT-x或AMD-V。这个坑我踩过两次第一次以为是Docker版本问题重装了三遍才发现是BIOS设置没开。装完Docker后验证一下docker --version docker compose version然后创建项目目录结构hindsight-agent/ ├── docker-compose.yml ├── mcp-server/ │ ├── Dockerfile │ ├── requirements.txt │ └── server.py ├── qdrant/ │ └── data/ └── redis/ └── data/docker-compose.yml的内容大致如下version: 3.8 services: qdrant: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - ./qdrant/data:/qdrant/storage restart: unless-stopped redis: image: redis:7-alpine ports: - 6379:6379 volumes: - ./redis/data:/data restart: unless-stopped mcp-server: build: ./mcp-server ports: - 8080:8080 environment: - QDRANT_URLhttp://qdrant:6333 - REDIS_URLredis://redis:6379 depends_on: - qdrant - redis restart: unless-stopped提示Qdrant的默认端口是6333HTTP和6334gRPC。如果你本机已经装了其他向量数据库占用了6333记得改端口映射否则启动会报端口冲突。4.2 MCP Server核心代码实现server.py里实现记忆的读写和检索。先装依赖pip install mcp qdrant-client redis sentence-transformers然后写核心逻辑import json import time from datetime import datetime, timedelta from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio import mcp.types as types from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct from sentence_transformers import SentenceTransformer import redis import os app Server(hindsight-memory) # 初始化连接 qdrant QdrantClient(urlos.getenv(QDRANT_URL, http://localhost:6333)) redis_client redis.from_url(os.getenv(REDIS_URL, redis://localhost:6379)) encoder SentenceTransformer(all-MiniLM-L6-v2) COLLECTION_NAME agent_memory VECTOR_DIM 384 # 确保collection存在 collections [c.name for c in qdrant.get_collections().collections] if COLLECTION_NAME not in collections: qdrant.create_collection( collection_nameCOLLECTION_NAME, vectors_configVectorParams(sizeVECTOR_DIM, distanceDistance.COSINE) ) app.list_tools() async def list_tools() - list[types.Tool]: return [ types.Tool( namememory_write, description写入一条新的Agent记忆, inputSchema{ type: object, properties: { content: {type: string, description: 记忆内容}, memory_type: {type: string, enum: [episodic, semantic]}, metadata: {type: object, description: 附加元数据} }, required: [content, memory_type] } ), types.Tool( namememory_search, description检索相关记忆, inputSchema{ type: object, properties: { query: {type: string}, top_k: {type: integer, default: 5}, days_limit: {type: integer, default: 90} }, required: [query] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict) - list[types.TextContent]: if name memory_write: content arguments[content] memory_type arguments[memory_type] metadata arguments.get(metadata, {}) vector encoder.encode(content).tolist() point_id int(time.time() * 1000) qdrant.upsert( collection_nameCOLLECTION_NAME, points[PointStruct( idpoint_id, vectorvector, payload{ content: content, memory_type: memory_type, timestamp: datetime.now().isoformat(), **metadata } )] ) return [types.TextContent(typetext, textf记忆已写入ID: {point_id})] elif name memory_search: query arguments[query] top_k arguments.get(top_k, 5) days_limit arguments.get(days_limit, 90) query_vector encoder.encode(query).tolist() cutoff datetime.now() - timedelta(daysdays_limit) results qdrant.search( collection_nameCOLLECTION_NAME, query_vectorquery_vector, limittop_k * 2, query_filter{ must: [ {key: timestamp, range: {gte: cutoff.isoformat()}} ] } ) # 时间衰减重排序 scored [] for r in results: ts datetime.fromisoformat(r.payload[timestamp]) days_ago (datetime.now() - ts).days decay pow(2.718, -0.03 * days_ago) final_score r.score * decay scored.append((final_score, r.payload[content])) scored.sort(keylambda x: x[0], reverseTrue) top_results scored[:top_k] output \n---\n.join([f[相关度: {s:.3f}] {c} for s, c in top_results]) return [types.TextContent(typetext, textoutput or 未找到相关记忆)]这段代码里有两个关键设计。一是时间衰减用了exp(-0.03 * days_ago)意味着30天前的记忆权重衰减到约40%90天前的衰减到约7%。这个系数可以根据业务调整客服场景可以调小到0.01让记忆保留更久。二是检索时先取top_k * 2条再做时间衰减重排序这样避免因为时间因素漏掉高相似度但稍旧的记忆。4.3 与Agent框架的对接MCP Server跑起来之后Agent端需要配置MCP Client来连接。以Claude Desktop为例在配置文件中添加{ mcpServers: { hindsight-memory: { command: docker, args: [exec, -i, hindsight-agent-mcp-server-1, python, server.py] } } }如果是远程SSE模式配置改成{ mcpServers: { hindsight-memory: { url: http://localhost:8080/sse } } }对接完成后Agent在对话过程中就可以自动调用memory_write和memory_search。我通常会在系统提示词里加一段引导你拥有长期记忆能力。当用户提到过去的交互、个人偏好或重要计划时 使用memory_search检索相关记忆。当用户透露新的重要信息时 使用memory_write将其存入记忆。注意不要让Agent每轮对话都无条件调用memory_search那样会显著增加延迟。更好的做法是在系统提示词里定义触发条件比如“当用户使用‘上次’、‘之前’、‘我记得’等回溯性词汇时”才触发检索。5. 常见问题与排查技巧实录5.1 记忆检索返回不相关结果这是最常见的问题。排查思路分三步走。第一步检查embedding模型是否适合当前语言。all-MiniLM-L6-v2对英文效果很好但中文语义区分度一般。如果主要处理中文对话建议换成BAAI/bge-small-zh-v1.5或text2vec-base-chinese。换模型后需要重建collection因为向量维度可能不同。第二步检查记忆写入时是否做了噪声过滤。如果打分阈值设得太低大量寒暄和确认性回复“好的”、“明白了”也会被写入检索时自然容易命中这些无意义内容。建议在写入前加一道规则过滤把长度小于10个字符且不含实词的内容直接丢弃。第三步检查时间衰减系数是否过大。如果λ设成0.1那7天前的记忆权重就衰减到50%以下可能导致旧但重要的记忆被新但无关的记忆挤掉。这种情况下把λ调小到0.02左右再试。5.2 Docker容器启动后MCP Server连接失败先看容器日志docker compose logs mcp-server如果报Connection refused到Qdrant通常是网络问题。Docker Compose默认会创建一个内部网络服务之间用服务名互相访问。确认docker-compose.yml里MCP Server的环境变量用的是http://qdrant:6333而不是http://localhost:6333。后者在容器内部指向的是容器自己不是宿主机。如果报端口冲突用docker ps看哪个容器占用了8080或6333改一下映射端口即可。还有一个隐蔽的坑Windows下Docker Desktop的WSL2后端有时候会出现网络不通的情况表现为容器能启动但互相ping不通。解决办法是在Docker Desktop设置里重启WSL2集成或者执行wsl --shutdown后重新启动Docker。5.3 记忆写入后检索不到先确认写入是否成功。直接查Qdrant的collectioncurl http://localhost:6333/collections/agent_memory看points_count是否增加。如果没增加说明写入请求没到达Qdrant检查MCP Server日志里的错误信息。如果写入成功但检索不到大概率是时间过滤条件把结果筛掉了。检查days_limit参数是否设得太小或者记忆的timestamp字段格式是否正确。我遇到过一次因为时区问题导致timestamp比实际时间早8小时结果刚写入的记忆被时间过滤器排除了。解决办法是统一用UTC时间存储检索时也转成UTC比较。5.4 常见问题速查表问题现象可能原因排查方法解决方案检索结果不相关embedding模型语言不匹配用中文query测试相似度换用中文embedding模型检索结果不相关噪声记忆过多查看collection中低分记忆占比提高写入打分阈值检索结果不相关时间衰减过大检查λ系数调小λ至0.01-0.03MCP连接失败容器网络配置错误docker compose logs改用服务名而非localhost记忆写入失败Qdrant collection不存在curl查collection列表在Server启动时自动创建记忆检索为空时间过滤条件过严检查timestamp和days_limit统一UTC时间放宽天数响应延迟高每轮都触发检索查看调用日志改为条件触发检索5.5 几个我踩过的坑和对应技巧第一个坑是embedding模型加载慢。sentence-transformers首次加载模型时会从HuggingFace下载权重如果网络环境不稳定容器启动会卡住。解决办法是提前把模型下载到本地在Dockerfile里COPY进去或者挂载一个本地缓存目录。第二个坑是Qdrant的持久化。默认情况下Qdrant把数据存在容器内部容器一删数据就没了。必须在docker-compose.yml里配置volume映射把/qdrant/storage映射到宿主机目录。这个我吃过一次亏调试时重启容器发现所有记忆都没了白测了一下午。第三个坑是MCP Server的并发处理。stdio模式下MCP Server是单线程的如果同时有多个Agent实例连接会出现请求排队。生产环境一定要用SSE模式并且给Server加上异步处理。Python的mcp库支持asyncio把耗时的embedding计算放到线程池里执行避免阻塞主事件循环。6. 记忆系统的演进方向与扩展思路6.1 从被动检索到主动遗忘现在的记忆系统大多是“只增不减”时间长了collection会越来越大检索效率下降噪声比例上升。下一步我打算加入主动遗忘机制定期扫描episodic memory把超过一定时间未被检索到的记忆降权或归档对于semantic memory如果新的归纳结果与旧的发生冲突自动用新的覆盖旧的。具体实现上可以给每条记忆加一个last_accessed字段每次被检索到就更新。后台跑一个定时任务把90天内last_accessed未更新的记忆标记为archived检索时默认排除。这样既保留了数据又不会影响检索质量。6.2 记忆的图结构组织纯向量检索的一个局限是丢失了记忆之间的关联。比如用户先说“我养了一只猫”后来说“它最近生病了”这两条记忆在向量空间里可能距离较远但语义上是强关联的。用图结构组织记忆把实体猫作为节点把关系生病作为边检索时就可以做多跳推理。这个方向可以参考GraphRAG的思路用LLM从对话中抽取实体和关系构建知识图谱。检索时先定位实体节点再沿边扩展相关记忆。实现复杂度比纯向量方案高不少但对于需要深度推理的场景效果提升很明显。6.3 多Agent共享记忆当系统里有多个Agent时记忆的隔离和共享是个问题。我的做法是用namespace区分每个Agent有自己私有的记忆空间同时有一个共享空间存放跨Agent的公共知识。MCP Server在检索时同时查两个空间按权重合并结果。私有记忆权重高公共记忆权重低避免公共信息淹没个性化信息。这个方案在客服场景里很实用每个客服Agent记住自己跟过的用户偏好同时共享产品知识库和常见问题解答。新Agent上线时共享记忆直接可用不需要从零积累。6.4 记忆压缩与摘要生成当episodic memory积累到一定量单条检索已经不够高效时需要做记忆压缩。我通常按周或按月做一次批量摘要把同一时间段内的记忆按主题聚类每个簇生成一段摘要存入semantic memory原始记忆标记为已压缩。检索时优先查semantic memory如果摘要不够具体再回溯到原始episodic memory。摘要生成的prompt要控制好粒度。太粗会丢失细节太细又起不到压缩效果。我的经验是每段摘要控制在200-300字覆盖5-10条原始记忆。摘要里要保留具体的时间、人物、事件但可以省略对话的原始措辞。这套hindsight记忆系统我从最初的原型到现在稳定运行大概迭代了六七个版本。最大的体会是记忆系统的难点不在存储而在取舍。什么该记、什么该忘、什么时候该查、查多少条这些策略层面的决策比技术选型更影响最终效果。技术方案可以抄但这些策略参数必须根据自己的业务场景反复调优。我现在每上线一个新场景第一件事就是跑一周的日志看记忆命中率和噪声比例然后针对性调整打分阈值和检索参数。这个过程没有捷径但一旦调好Agent的“记性”会有质的提升。
基于MCP协议的LLM Agent长期记忆系统设计与Docker部署实战
1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词是在一个做LLM Agent的朋友群里。有人丢了一张截图说他们的Agent在连续对话到第37轮的时候突然把用户三小时前说过的偏好设置忘得一干二净回复开始胡言乱语。底下有人回了一句“这不就是典型的没有hindsight吗——它只能看见眼前看不见身后。”这个词翻译过来叫“后见之明”但在Agent memory的语境里它指的是一套让LLM Agent能够回溯、检索、利用历史交互信息的记忆机制。你可以把它理解成给Agent装了一面后视镜它不改变车往哪开但能让驾驶者知道刚才经过了什么、有没有漏掉该拐的路口。我接触Agent memory这个方向大概有一年多时间从最早的简单滑动窗口到后来的向量数据库检索再到最近结合MCP协议做跨会话记忆持久化踩过的坑比写过的代码还多。这篇文章想聊的就是围绕“hindsight”这个核心概念把Agent memory从设计思路到落地实操的完整链路拆开来讲。不管你是刚接触LLM应用开发的新手还是已经在做多轮对话系统的老手应该都能从里面找到一些可以直接抄作业的东西。先明确一下这篇文章要解决的问题域当一个LLM Agent需要记住用户说过的话、做过的操作、形成的偏好并且在后续对话中准确调用这些信息时它的记忆系统应该怎么设计存储层用什么检索策略怎么定MCP协议在这里扮演什么角色Docker部署时有哪些坑这些都是实打实要面对的问题。2. Agent memory的核心设计思路拆解2.1 为什么滑动窗口不够用从“失忆”说起大部分LLM应用最开始都是靠上下文窗口硬扛。用户问一句模型答一句把最近N轮对话拼成prompt塞进去。这种做法在短对话里没问题但一旦对话轮次超过二三十轮就会遇到两个硬瓶颈。第一个瓶颈是token成本。假设每轮对话平均200个token30轮就是6000个token再加上系统提示词和工具描述轻松破万。如果每轮都全量携带API调用成本会线性增长响应延迟也会肉眼可见地变慢。第二个瓶颈更致命即使你愿意花钱把全部历史塞进去模型对长上下文的注意力分配也是不均匀的。大量实验表明LLM对上下文中间部分的信息召回率明显低于开头和结尾这就是所谓的“lost in the middle”现象。所以Agent memory要解决的核心问题不是“能不能存”而是“存什么、怎么取、什么时候取”。hindsight这个概念的价值就在于它强调的是一种主动回溯的能力——不是被动地把所有历史都塞给模型而是让Agent在需要的时候能够精准地“回头看”。2.2 三层记忆架构working memory、episodic memory、semantic memory参考认知科学里对人类记忆的分类我在实际项目中通常把Agent memory分成三层。Working memory对应的是当前会话的短期上下文生命周期就是一次会话。它存储的是最近几轮对话的原始文本通常用滑动窗口加摘要的方式管理。当窗口满了就把最老的那部分对话压缩成一段摘要保留关键信息丢弃冗余表达。Episodic memory对应的是跨会话的事件记忆。比如用户上周三说过“我下个月要搬家”这条信息在当前会话结束后不应该消失而应该被持久化下来等到用户下次提到搬家相关话题时能够被检索出来。这一层通常用向量数据库存储每条记忆是一个独立的embedding向量附带时间戳和元数据。Semantic memory对应的是从多次交互中抽象出来的规律性知识。比如Agent通过多次对话发现某个用户总是偏好简洁的回答风格这个“偏好简洁”就是一个semantic memory。它不依赖于某一次具体交互而是从episodic memory中归纳出来的。这三层不是孤立的而是有明确的读写路径。Working memory在会话结束时由LLM判断哪些信息值得写入episodic memoryepisodic memory积累到一定量后再通过聚类或摘要生成semantic memory。检索时优先查working memory不够再查episodic最后查semantic。2.3 为什么选MCP而不是自己写一套APIMCPModel Context Protocol在这套架构里的角色是标准化Agent与外部记忆存储之间的通信接口。在没有MCP之前每个Agent框架都有自己的工具调用格式OpenAI的function calling、Anthropic的tool use、LangChain的Tool接口各不相同。你要换一个LLM提供商记忆模块的对接代码就得重写一遍。MCP把这个过程标准化了。它定义了一套基于JSON-RPC的协议Agent通过MCP Server暴露记忆读写能力LLM通过MCP Client调用这些能力。好处是解耦记忆存储的实现可以独立演进只要MCP接口不变上层Agent就不用改代码。而且MCP天然支持流式传输和双向通信对于需要实时写入记忆的场景很友好。我实测下来用MCP做记忆层抽象切换底层存储从Redis到Postgres到Qdrant的时间从原来的两三天缩短到半天以内。这个收益在快速迭代阶段非常明显。3. 核心细节解析与实操要点3.1 记忆写入策略什么时候该记什么时候该忘这是整个系统里最难调的部分。记太多检索时噪声大模型容易被无关信息干扰记太少关键信息丢失Agent显得“没记性”。我的经验是采用“LLM打分规则过滤”的双层策略。每轮对话结束后把用户输入和Agent回复一起送给一个轻量级LLM比如7B级别的模型让它从三个维度打分信息密度、时效性、可复用性。三个维度加权求和超过阈值的才写入episodic memory。具体打分prompt可以这样设计MEMORY_SCORING_PROMPT 你是一个记忆重要性评估器。请对以下对话片段进行打分每个维度1-5分。 对话内容 用户{user_input} 助手{assistant_response} 评分维度 1. 信息密度是否包含具体的事实、偏好、计划或约束条件 2. 时效性这条信息是否在近期内可能被再次提及 3. 可复用性这条信息是否适用于未来的多次交互 请以JSON格式输出{{density: score, timeliness: score, reusability: score}} 阈值设定上我一般取加权平均3.5分。低于这个分数的对话片段直接丢弃不进入长期记忆。这个阈值可以根据业务场景调整客服场景可以调低到3.0因为用户说的每句话可能都有用闲聊场景可以调高到4.0避免存储大量无意义寒暄。注意打分模型和主对话模型最好分开。用同一个大模型既做对话又做记忆评估会导致token消耗翻倍而且评估结果容易受对话上下文干扰。用一个小的、专门的模型做评估成本更低判断也更稳定。3.2 记忆检索向量相似度不是万能的很多人一提到记忆检索就想到向量数据库觉得把记忆embedding存进去查询时算余弦相似度就完事了。实际用下来纯向量检索有三个明显问题。第一时间衰减被忽略。三个月前的一条记忆和昨天的一条记忆如果向量相似度差不多应该优先返回哪条显然是最近的。所以检索分数里必须加入时间衰减因子。我通常用指数衰减score similarity * exp(-λ * days_ago)λ取0.01到0.05之间具体看业务对时效性的敏感程度。第二关键词匹配仍然重要。用户说“帮我订上次那家餐厅”向量检索可能返回一堆餐厅相关的记忆但“上次”这个时间指示词需要结合时间戳过滤才能准确定位。所以我在检索时会同时跑一路BM25关键词检索然后把两路结果做融合排序。第三检索数量要控制。返回太多记忆会挤占上下文窗口返回太少可能漏掉关键信息。我的经验值是top-5到top-8之间具体取决于单条记忆的平均长度。如果单条记忆超过200token就取top-5如果比较短可以取top-8。3.3 MCP Server的实现要点用MCP协议暴露记忆能力需要实现几个核心工具toolmemory_write写入一条新记忆参数包括内容、类型episodic/semantic、元数据memory_search根据查询文本检索相关记忆参数包括查询、top_k、时间范围memory_forget删除指定记忆用于用户主动要求“忘记”的场景memory_summarize对一段时间范围内的记忆做摘要用于生成semantic memoryMCP Server的实现可以用Python的mcp库也可以用TypeScript的modelcontextprotocol/sdk。我两种都用过Python版在数据处理生态上更顺手TypeScript版在流式传输和并发处理上更自然。如果记忆存储用的是向量数据库Python版可以直接调用qdrant-client或chromadb代码量更少。一个容易踩的坑是MCP Server的启动方式。如果你用Docker部署MCP Server需要以stdio或SSE模式运行。stdio模式适合本地开发Agent和Server在同一台机器上SSE模式适合远程部署Agent通过HTTP连接到Server。我建议开发阶段用stdio生产环境用SSE因为SSE支持多客户端并发连接而且更容易做鉴权和限流。4. 实操过程与核心环节实现4.1 环境准备Docker与依赖安装整套系统的部署我推荐用Docker Compose编排把MCP Server、向量数据库、Redis做working memory缓存放在同一个网络里。这样Agent只需要连接MCP Server的端口不需要关心底层存储的具体地址。先装Docker Desktop。Windows用户注意安装过程中如果提示“Virtualization support not detected”需要进BIOS开启CPU虚拟化Intel VT-x或AMD-V。这个坑我踩过两次第一次以为是Docker版本问题重装了三遍才发现是BIOS设置没开。装完Docker后验证一下docker --version docker compose version然后创建项目目录结构hindsight-agent/ ├── docker-compose.yml ├── mcp-server/ │ ├── Dockerfile │ ├── requirements.txt │ └── server.py ├── qdrant/ │ └── data/ └── redis/ └── data/docker-compose.yml的内容大致如下version: 3.8 services: qdrant: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - ./qdrant/data:/qdrant/storage restart: unless-stopped redis: image: redis:7-alpine ports: - 6379:6379 volumes: - ./redis/data:/data restart: unless-stopped mcp-server: build: ./mcp-server ports: - 8080:8080 environment: - QDRANT_URLhttp://qdrant:6333 - REDIS_URLredis://redis:6379 depends_on: - qdrant - redis restart: unless-stopped提示Qdrant的默认端口是6333HTTP和6334gRPC。如果你本机已经装了其他向量数据库占用了6333记得改端口映射否则启动会报端口冲突。4.2 MCP Server核心代码实现server.py里实现记忆的读写和检索。先装依赖pip install mcp qdrant-client redis sentence-transformers然后写核心逻辑import json import time from datetime import datetime, timedelta from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio import mcp.types as types from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct from sentence_transformers import SentenceTransformer import redis import os app Server(hindsight-memory) # 初始化连接 qdrant QdrantClient(urlos.getenv(QDRANT_URL, http://localhost:6333)) redis_client redis.from_url(os.getenv(REDIS_URL, redis://localhost:6379)) encoder SentenceTransformer(all-MiniLM-L6-v2) COLLECTION_NAME agent_memory VECTOR_DIM 384 # 确保collection存在 collections [c.name for c in qdrant.get_collections().collections] if COLLECTION_NAME not in collections: qdrant.create_collection( collection_nameCOLLECTION_NAME, vectors_configVectorParams(sizeVECTOR_DIM, distanceDistance.COSINE) ) app.list_tools() async def list_tools() - list[types.Tool]: return [ types.Tool( namememory_write, description写入一条新的Agent记忆, inputSchema{ type: object, properties: { content: {type: string, description: 记忆内容}, memory_type: {type: string, enum: [episodic, semantic]}, metadata: {type: object, description: 附加元数据} }, required: [content, memory_type] } ), types.Tool( namememory_search, description检索相关记忆, inputSchema{ type: object, properties: { query: {type: string}, top_k: {type: integer, default: 5}, days_limit: {type: integer, default: 90} }, required: [query] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict) - list[types.TextContent]: if name memory_write: content arguments[content] memory_type arguments[memory_type] metadata arguments.get(metadata, {}) vector encoder.encode(content).tolist() point_id int(time.time() * 1000) qdrant.upsert( collection_nameCOLLECTION_NAME, points[PointStruct( idpoint_id, vectorvector, payload{ content: content, memory_type: memory_type, timestamp: datetime.now().isoformat(), **metadata } )] ) return [types.TextContent(typetext, textf记忆已写入ID: {point_id})] elif name memory_search: query arguments[query] top_k arguments.get(top_k, 5) days_limit arguments.get(days_limit, 90) query_vector encoder.encode(query).tolist() cutoff datetime.now() - timedelta(daysdays_limit) results qdrant.search( collection_nameCOLLECTION_NAME, query_vectorquery_vector, limittop_k * 2, query_filter{ must: [ {key: timestamp, range: {gte: cutoff.isoformat()}} ] } ) # 时间衰减重排序 scored [] for r in results: ts datetime.fromisoformat(r.payload[timestamp]) days_ago (datetime.now() - ts).days decay pow(2.718, -0.03 * days_ago) final_score r.score * decay scored.append((final_score, r.payload[content])) scored.sort(keylambda x: x[0], reverseTrue) top_results scored[:top_k] output \n---\n.join([f[相关度: {s:.3f}] {c} for s, c in top_results]) return [types.TextContent(typetext, textoutput or 未找到相关记忆)]这段代码里有两个关键设计。一是时间衰减用了exp(-0.03 * days_ago)意味着30天前的记忆权重衰减到约40%90天前的衰减到约7%。这个系数可以根据业务调整客服场景可以调小到0.01让记忆保留更久。二是检索时先取top_k * 2条再做时间衰减重排序这样避免因为时间因素漏掉高相似度但稍旧的记忆。4.3 与Agent框架的对接MCP Server跑起来之后Agent端需要配置MCP Client来连接。以Claude Desktop为例在配置文件中添加{ mcpServers: { hindsight-memory: { command: docker, args: [exec, -i, hindsight-agent-mcp-server-1, python, server.py] } } }如果是远程SSE模式配置改成{ mcpServers: { hindsight-memory: { url: http://localhost:8080/sse } } }对接完成后Agent在对话过程中就可以自动调用memory_write和memory_search。我通常会在系统提示词里加一段引导你拥有长期记忆能力。当用户提到过去的交互、个人偏好或重要计划时 使用memory_search检索相关记忆。当用户透露新的重要信息时 使用memory_write将其存入记忆。注意不要让Agent每轮对话都无条件调用memory_search那样会显著增加延迟。更好的做法是在系统提示词里定义触发条件比如“当用户使用‘上次’、‘之前’、‘我记得’等回溯性词汇时”才触发检索。5. 常见问题与排查技巧实录5.1 记忆检索返回不相关结果这是最常见的问题。排查思路分三步走。第一步检查embedding模型是否适合当前语言。all-MiniLM-L6-v2对英文效果很好但中文语义区分度一般。如果主要处理中文对话建议换成BAAI/bge-small-zh-v1.5或text2vec-base-chinese。换模型后需要重建collection因为向量维度可能不同。第二步检查记忆写入时是否做了噪声过滤。如果打分阈值设得太低大量寒暄和确认性回复“好的”、“明白了”也会被写入检索时自然容易命中这些无意义内容。建议在写入前加一道规则过滤把长度小于10个字符且不含实词的内容直接丢弃。第三步检查时间衰减系数是否过大。如果λ设成0.1那7天前的记忆权重就衰减到50%以下可能导致旧但重要的记忆被新但无关的记忆挤掉。这种情况下把λ调小到0.02左右再试。5.2 Docker容器启动后MCP Server连接失败先看容器日志docker compose logs mcp-server如果报Connection refused到Qdrant通常是网络问题。Docker Compose默认会创建一个内部网络服务之间用服务名互相访问。确认docker-compose.yml里MCP Server的环境变量用的是http://qdrant:6333而不是http://localhost:6333。后者在容器内部指向的是容器自己不是宿主机。如果报端口冲突用docker ps看哪个容器占用了8080或6333改一下映射端口即可。还有一个隐蔽的坑Windows下Docker Desktop的WSL2后端有时候会出现网络不通的情况表现为容器能启动但互相ping不通。解决办法是在Docker Desktop设置里重启WSL2集成或者执行wsl --shutdown后重新启动Docker。5.3 记忆写入后检索不到先确认写入是否成功。直接查Qdrant的collectioncurl http://localhost:6333/collections/agent_memory看points_count是否增加。如果没增加说明写入请求没到达Qdrant检查MCP Server日志里的错误信息。如果写入成功但检索不到大概率是时间过滤条件把结果筛掉了。检查days_limit参数是否设得太小或者记忆的timestamp字段格式是否正确。我遇到过一次因为时区问题导致timestamp比实际时间早8小时结果刚写入的记忆被时间过滤器排除了。解决办法是统一用UTC时间存储检索时也转成UTC比较。5.4 常见问题速查表问题现象可能原因排查方法解决方案检索结果不相关embedding模型语言不匹配用中文query测试相似度换用中文embedding模型检索结果不相关噪声记忆过多查看collection中低分记忆占比提高写入打分阈值检索结果不相关时间衰减过大检查λ系数调小λ至0.01-0.03MCP连接失败容器网络配置错误docker compose logs改用服务名而非localhost记忆写入失败Qdrant collection不存在curl查collection列表在Server启动时自动创建记忆检索为空时间过滤条件过严检查timestamp和days_limit统一UTC时间放宽天数响应延迟高每轮都触发检索查看调用日志改为条件触发检索5.5 几个我踩过的坑和对应技巧第一个坑是embedding模型加载慢。sentence-transformers首次加载模型时会从HuggingFace下载权重如果网络环境不稳定容器启动会卡住。解决办法是提前把模型下载到本地在Dockerfile里COPY进去或者挂载一个本地缓存目录。第二个坑是Qdrant的持久化。默认情况下Qdrant把数据存在容器内部容器一删数据就没了。必须在docker-compose.yml里配置volume映射把/qdrant/storage映射到宿主机目录。这个我吃过一次亏调试时重启容器发现所有记忆都没了白测了一下午。第三个坑是MCP Server的并发处理。stdio模式下MCP Server是单线程的如果同时有多个Agent实例连接会出现请求排队。生产环境一定要用SSE模式并且给Server加上异步处理。Python的mcp库支持asyncio把耗时的embedding计算放到线程池里执行避免阻塞主事件循环。6. 记忆系统的演进方向与扩展思路6.1 从被动检索到主动遗忘现在的记忆系统大多是“只增不减”时间长了collection会越来越大检索效率下降噪声比例上升。下一步我打算加入主动遗忘机制定期扫描episodic memory把超过一定时间未被检索到的记忆降权或归档对于semantic memory如果新的归纳结果与旧的发生冲突自动用新的覆盖旧的。具体实现上可以给每条记忆加一个last_accessed字段每次被检索到就更新。后台跑一个定时任务把90天内last_accessed未更新的记忆标记为archived检索时默认排除。这样既保留了数据又不会影响检索质量。6.2 记忆的图结构组织纯向量检索的一个局限是丢失了记忆之间的关联。比如用户先说“我养了一只猫”后来说“它最近生病了”这两条记忆在向量空间里可能距离较远但语义上是强关联的。用图结构组织记忆把实体猫作为节点把关系生病作为边检索时就可以做多跳推理。这个方向可以参考GraphRAG的思路用LLM从对话中抽取实体和关系构建知识图谱。检索时先定位实体节点再沿边扩展相关记忆。实现复杂度比纯向量方案高不少但对于需要深度推理的场景效果提升很明显。6.3 多Agent共享记忆当系统里有多个Agent时记忆的隔离和共享是个问题。我的做法是用namespace区分每个Agent有自己私有的记忆空间同时有一个共享空间存放跨Agent的公共知识。MCP Server在检索时同时查两个空间按权重合并结果。私有记忆权重高公共记忆权重低避免公共信息淹没个性化信息。这个方案在客服场景里很实用每个客服Agent记住自己跟过的用户偏好同时共享产品知识库和常见问题解答。新Agent上线时共享记忆直接可用不需要从零积累。6.4 记忆压缩与摘要生成当episodic memory积累到一定量单条检索已经不够高效时需要做记忆压缩。我通常按周或按月做一次批量摘要把同一时间段内的记忆按主题聚类每个簇生成一段摘要存入semantic memory原始记忆标记为已压缩。检索时优先查semantic memory如果摘要不够具体再回溯到原始episodic memory。摘要生成的prompt要控制好粒度。太粗会丢失细节太细又起不到压缩效果。我的经验是每段摘要控制在200-300字覆盖5-10条原始记忆。摘要里要保留具体的时间、人物、事件但可以省略对话的原始措辞。这套hindsight记忆系统我从最初的原型到现在稳定运行大概迭代了六七个版本。最大的体会是记忆系统的难点不在存储而在取舍。什么该记、什么该忘、什么时候该查、查多少条这些策略层面的决策比技术选型更影响最终效果。技术方案可以抄但这些策略参数必须根据自己的业务场景反复调优。我现在每上线一个新场景第一件事就是跑一周的日志看记忆命中率和噪声比例然后针对性调整打分阈值和检索参数。这个过程没有捷径但一旦调好Agent的“记性”会有质的提升。
