1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词我脑子里蹦出来的不是词典里的“事后聪明”而是开车时那面后视镜。你往前开眼睛盯着前方路况但真正让你敢变道、敢超车的是后视镜里那几秒前的画面。Agent Memory这件事本质上就是在给LLM驱动的智能体装一面足够聪明的后视镜——让它记得刚才发生了什么从而决定下一步怎么走。这个项目标题“hindsight”放在Agent Memory的语境下指向非常明确构建一套面向LLM Agent的记忆管理系统。它要解决的问题很具体——当前大多数Agent在单轮对话或短任务里表现不错一旦任务链条拉长、交互轮次变多就开始“失忆”。你上一轮告诉它“用Python 3.11别用3.12”下一轮它给你生成一个3.12的依赖安装命令。你前面说“数据库用PostgreSQL”后面它给你写MySQL的DDL。这不是模型笨是它根本没有一个可靠的机制把关键信息存下来、在需要的时候取出来。“hindsight”这个命名本身就带着一种设计哲学记忆不是简单的日志堆积而是对过去经验的重新审视和选择性提取。就像人回忆事情你不是把过去每一秒都回放一遍而是根据当前问题从记忆里捞出最相关的片段。这套系统要做的就是让Agent具备这种“按需回忆”的能力。适合谁来参考这篇内容如果你正在做LLM应用开发尤其是涉及多轮对话、长任务编排、工具调用链路的场景那Agent Memory是你绕不过去的坎。如果你只是调用API做单轮问答那暂时用不上。但只要你开始碰MCP协议、开始让Agent调用外部工具、开始处理超过10轮以上的交互记忆管理就会从“锦上添花”变成“不做不行”。我见过太多项目在Demo阶段惊艳一上生产就崩核心原因之一就是记忆没管好。用户说“帮我订明天去上海的机票”Agent查了航班用户说“要上午的”Agent又查了一遍用户说“还是上次那个航空公司”Agent直接懵了——“上次”是哪次没有记忆就没有上下文连续性就没有真正的智能。2. Agent Memory的核心设计思路与方案选型2.1 为什么传统RAG不够用很多人第一反应是记忆嘛不就是把历史对话存进向量数据库用的时候检索一下这个思路对了一半但远远不够。传统RAG面向的是静态知识库文档不变查询模式相对固定。Agent Memory面对的是动态交互流每一轮对话都在产生新信息而且这些信息的“重要性”差异极大。举个例子。用户说“你好”和用户说“我的API Key是sk-xxx请记住”这两句话在向量空间里的距离可能差不多但对Agent来说后者必须被精确记住前者可以丢弃。传统RAG的相似度检索没法区分这种“重要性权重”。你需要一套更精细的记忆管理机制。我在实际项目里踩过的坑早期版本把所有对话历史一股脑塞进向量库结果检索时经常捞出一堆“好的”“明白了”“继续”这种废话真正关键的信息反而被淹没了。后来引入记忆分层才解决这个问题。2.2 记忆分层的设计逻辑“hindsight”这套思路里记忆至少分三层第一层工作记忆Working Memory。这是Agent当前正在处理的任务上下文容量有限通常就是最近几轮对话加上当前任务的状态变量。它相当于人的“短期记忆”容量小但访问极快。实现上一般就是直接放在Prompt的上下文窗口里或者用一个结构化的状态对象来维护。第二层情景记忆Episodic Memory。这是对过去交互事件的记录包括每次任务的目标、执行过程、结果、用户反馈。它相当于人的“经历记忆”——你记得上周做过一个类似的项目但具体细节可能模糊了。实现上通常用向量数据库存储配合时间戳和任务标签做过滤。第三层语义记忆Semantic Memory。这是从多次交互中提炼出来的通用知识和偏好。比如“这个用户偏好用Python而不是JavaScript”“这个项目的数据库规范是PostgreSQL”。它相当于人的“常识和技能记忆”不依赖具体场景可以跨任务复用。实现上可以用键值对存储或者用轻量级的知识图谱。这三层的读写策略完全不同。工作记忆是高频读写情景记忆是写多读少语义记忆是低频写、高频读。如果你用同一套存储机制处理所有层性能和维护都会出问题。2.3 为什么选择MCP作为集成协议MCPModel Context Protocol在这套架构里扮演的是“记忆总线”的角色。Agent需要调用记忆服务时不是直接连数据库而是通过MCP协议暴露的接口来操作。这样做的好处有几个第一解耦。记忆服务的实现可以独立演进Agent不需要关心底层用的是Redis还是PostgreSQL还是向量库。第二标准化。MCP定义了工具调用的统一格式记忆的读写、检索、更新都可以封装成标准的ToolAgent通过Function Calling来触发。第三可观测。所有记忆操作都经过MCP层方便打日志、做审计、排查问题。我试过不用MCP直接让Agent调数据库结果是代码里到处散落着SQL和向量检索逻辑改一个字段要动好几个地方。后来统一走MCP记忆服务的接口稳定了Agent侧的代码干净了很多。2.4 Docker在其中的角色Docker解决的是“环境一致性”问题。Agent Memory系统通常涉及多个组件向量数据库、关系型数据库、缓存、MCP Server、Agent运行时。如果每个组件都手动装光是版本兼容就能耗掉一整天。用Docker Compose编排一条命令拉起全套环境换台机器也能复现。而且记忆服务往往需要持久化存储Docker Volume可以很好地管理数据卷。你不需要担心容器重启后数据丢失也不需要手动配置数据目录权限。对于开发和测试阶段这种便利性尤其重要。3. 核心细节解析与实操要点3.1 记忆的写入策略什么该记什么该忘这是整个系统里最难的部分。记太多检索时噪声大记太少关键信息丢失。我的经验是采用基于规则的过滤 基于重要性的评分双机制。规则层面以下几类信息必须写入情景记忆用户明确表达的偏好“我喜欢用TypeScript”任务的关键约束“预算不超过5000”工具调用的结果摘要“查询到3个航班”错误和异常“API返回429触发限流”以下几类信息可以丢弃或降权纯确认性回复“好的”“收到”重复信息用户第三次说“用Python”与当前任务无关的闲聊重要性评分可以用一个轻量级的LLM来做让模型对每轮对话打一个1-5分低于阈值的直接不进长期记忆。这个评分Prompt我调了好几版核心是让模型判断“如果未来Agent需要回忆这轮对话它有多大概率会用到这条信息”。注意不要用同一个LLM既做Agent推理又做记忆评分容易产生偏差。最好用一个小模型比如7B级别专门做记忆管理大模型专注任务执行。3.2 记忆的检索策略怎么捞到对的信息检索不是简单的向量相似度Top-K。我实际用下来混合检索效果最好向量相似度 关键词匹配 时间衰减 任务标签过滤。具体来说检索分数可以这样算final_score 0.5 * vector_similarity 0.2 * keyword_match 0.2 * recency_score 0.1 * task_relevance其中recency_score用指数衰减越近的记忆分数越高。task_relevance根据当前任务类型和记忆的任务标签做匹配。这个权重不是拍脑袋定的我做过A/B测试。纯向量检索的命中率大概60%加上关键词和时间衰减后能到80%左右。任务标签过滤在跨任务场景下提升最明显因为不同任务的记忆混在一起时标签能有效隔离噪声。还有一个技巧检索时返回原始文本而不是摘要。早期我为了节省Token把记忆压缩成摘要再存结果检索出来的摘要丢失了关键细节。后来改成存原始文本摘要双份检索用摘要做粗筛返回时给原始文本效果好很多。3.3 记忆的更新与遗忘机制记忆不是只增不减的。你需要一套遗忘机制否则存储会无限膨胀检索质量也会下降。我的做法是时间衰减超过30天未被访问的情景记忆自动降权或归档。冲突消解当新记忆与旧记忆冲突时比如用户先说“用MySQL”后说“改用PostgreSQL”保留新的旧的标记为“已废弃”但不删除以备追溯。容量上限每层记忆设一个上限超过后按重要性评分淘汰最低的。这里有个坑不要直接删除记忆。你永远不知道未来会不会需要回溯。标记为“归档”或“低优先级”就够了物理删除是不可逆的。3.4 MCP Tool的设计要点把记忆操作封装成MCP Tool时接口设计要遵循“粗粒度”原则。不要暴露insert_memory、update_memory、delete_memory这种细粒度操作给Agent而是提供remember、recall、forget三个高层接口。remember接收一段文本和可选的元数据任务标签、重要性内部自动决定存哪层、怎么存。recall接收查询文本和可选的过滤条件返回排序后的记忆列表。forget接收记忆ID或查询条件执行归档或降权。这样做的好处是Agent不需要理解记忆系统的内部结构只需要知道“我要记住这个”“我要回忆那个”。接口越简单Agent用错的概率越低。4. 实操过程与核心环节实现4.1 环境准备Docker Compose编排全套服务先上docker-compose.yml的核心配置。这套配置我在Ubuntu 22.04和macOS上都跑过Windows下用WSL2也没问题。version: 3.8 services: vector-db: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - ./data/qdrant:/qdrant/storage environment: - QDRANT__SERVICE__GRPC_PORT6334 cache: image: redis:7-alpine ports: - 6379:6379 volumes: - ./data/redis:/data command: redis-server --appendonly yes memory-service: build: ./memory-service ports: - 8080:8080 depends_on: - vector-db - cache environment: - QDRANT_URLhttp://vector-db:6333 - REDIS_URLredis://cache:6379 - LLM_API_KEY${LLM_API_KEY} volumes: - ./data/memory:/app/data mcp-server: build: ./mcp-server ports: - 3000:3000 depends_on: - memory-service environment: - MEMORY_SERVICE_URLhttp://memory-service:8080这里选Qdrant做向量库是因为它的过滤功能比较强支持在向量检索的同时做payload过滤正好适合我们“向量标签”的混合检索需求。Redis用来做工作记忆的缓存读写延迟低。memory-service是核心业务逻辑mcp-server是对外暴露的MCP接口。提示如果你在Windows上遇到“Virtualization support not detected”导致Docker Desktop起不来先去BIOS里确认VT-x/AMD-V已开启然后在Windows功能里勾选“虚拟机平台”和“适用于Linux的Windows子系统”。这两个都开了还不行就检查Hyper-V是否被其他软件占用。4.2 记忆服务的核心代码实现memory-service用Python FastAPI写核心是三个模块写入、检索、更新。写入模块的关键逻辑async def remember(content: str, metadata: dict): # 第一步重要性评分 importance await score_importance(content) if importance 0.3: return {status: skipped, reason: low_importance} # 第二步判断记忆层级 if metadata.get(type) preference: layer semantic elif metadata.get(task_id): layer episodic else: layer working # 第三步生成摘要和向量 summary await summarize(content) vector await embed(content) # 第四步写入对应存储 if layer working: await redis.setex( fworking:{metadata[session_id]}, 3600, json.dumps({content: content, summary: summary}) ) elif layer episodic: await qdrant.upsert( collection_nameepisodic, points[{ id: generate_id(), vector: vector, payload: { content: content, summary: summary, task_id: metadata[task_id], timestamp: time.time(), importance: importance } }] ) elif layer semantic: await qdrant.upsert( collection_namesemantic, points[{ id: generate_id(), vector: vector, payload: { content: content, summary: summary, category: metadata.get(category, general), timestamp: time.time() } }] ) return {status: ok, layer: layer, importance: importance}检索模块的核心是混合评分async def recall(query: str, filters: dict None, top_k: int 5): query_vector await embed(query) # 向量检索 vector_results await qdrant.search( collection_nameepisodic, query_vectorquery_vector, limittop_k * 3, query_filterbuild_filter(filters) ) # 关键词检索用Redis的全文搜索或简单的倒排索引 keyword_results await keyword_search(query, filters) # 合并去重 merged merge_results(vector_results, keyword_results) # 重排序 scored [] for item in merged: recency math.exp(-0.01 * (time.time() - item[timestamp]) / 86400) task_rel 1.0 if filters and item.get(task_id) filters.get(task_id) else 0.5 final (0.5 * item[vector_score] 0.2 * item[keyword_score] 0.2 * recency 0.1 * task_rel) scored.append((final, item)) scored.sort(keylambda x: x[0], reverseTrue) return [item for _, item in scored[:top_k]]更新模块处理冲突消解async def update_memory(memory_id: str, new_content: str): old await get_memory(memory_id) # 检查是否冲突 conflict await check_conflict(old[content], new_content) if conflict: # 旧记忆标记为废弃 await qdrant.set_payload( collection_nameepisodic, payload{status: deprecated, deprecated_at: time.time()}, points[memory_id] ) # 写入新记忆 await remember(new_content, old[metadata]) else: # 无冲突则合并 merged await merge_content(old[content], new_content) await qdrant.set_payload( collection_nameepisodic, payload{content: merged, updated_at: time.time()}, points[memory_id] )4.3 MCP Server的接口暴露MCP Server用Node.js写核心是把memory-service的HTTP接口转成MCP Tool。这里用官方SDKimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server({ name: hindsight-memory, version: 1.0.0 }, { capabilities: { tools: {} } }); server.setRequestHandler(tools/list, async () ({ tools: [ { name: remember, description: 记住一段信息用于后续回忆, inputSchema: { type: object, properties: { content: { type: string, description: 要记住的内容 }, type: { type: string, enum: [preference, fact, event] }, task_id: { type: string, description: 关联的任务ID } }, required: [content] } }, { name: recall, description: 回忆与查询相关的信息, inputSchema: { type: object, properties: { query: { type: string, description: 查询内容 }, task_id: { type: string, description: 限定任务范围 }, top_k: { type: number, default: 5 } }, required: [query] } }, { name: forget, description: 遗忘指定的记忆, inputSchema: { type: object, properties: { memory_id: { type: string }, query: { type: string } } } } ] })); server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name remember) { const result await fetch(http://memory-service:8080/remember, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(args) }); return { content: [{ type: text, text: JSON.stringify(await result.json()) }] }; } if (name recall) { const result await fetch(http://memory-service:8080/recall, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(args) }); return { content: [{ type: text, text: JSON.stringify(await result.json()) }] }; } // forget类似 }); const transport new StdioServerTransport(); await server.connect(transport);4.4 Agent侧的集成方式Agent侧通过MCP客户端连接这个Server然后在System Prompt里加入记忆使用的指引你拥有记忆能力。在以下情况下调用remember工具 - 用户表达了明确的偏好或约束 - 任务产生了关键结果或错误 - 你判断这条信息在未来对话中可能被用到 在以下情况下调用recall工具 - 用户提到“之前”“上次”“刚才”等指代词 - 当前任务需要参考历史决策 - 你不确定某个信息是否已经确认过 不要每轮对话都调用recall只在确实需要历史信息时调用。这个Prompt我迭代了七八版核心是让Agent知道“什么时候该记什么时候该回忆”。太频繁调用会拖慢响应速度太稀疏又起不到作用。实测下来平均每3-5轮对话触发一次记忆操作是比较合理的频率。5. 常见问题与排查技巧实录5.1 记忆检索返回不相关结果这是最常见的问题。排查思路按优先级来排查项可能原因解决方法向量模型嵌入模型不适合当前语言或领域换用多语言模型或领域微调模型分块策略记忆块太大或太小调整分块大小通常256-512 token较合适过滤条件标签过滤太严或太松检查task_id和category的匹配逻辑权重配置向量相似度权重过高降低向量权重提高关键词和时间权重数据质量记忆里混入了噪声检查重要性评分阈值是否太低我遇到过一次典型情况用户问“之前那个配置怎么写的”检索出来的全是“好的”“收到”这类确认性回复。原因是重要性评分模块的阈值设成了0.1几乎什么都往里存。调到0.3之后噪声明显减少。5.2 Docker容器间网络不通memory-service连不上vector-db报“Connection refused”。排查步骤确认两个服务在同一个Docker网络里。docker-compose默认会创建一个bridge网络所有服务都在里面。检查服务名是否写对。在容器里用ping vector-db测试注意不是localhost。检查端口。Qdrant的HTTP端口是6333gRPC是6334别搞混。检查防火墙。宿主机防火墙一般不影响容器间通信但如果你改了Docker的网络配置可能需要额外放行。提示在memory-service容器里执行curl http://vector-db:6333/healthz如果能返回OK说明网络没问题问题在应用层。5.3 记忆写入延迟高每次remember都要调LLM做重要性评分和摘要生成延迟自然高。优化方案异步写入Agent调用remember后立即返回实际写入在后台队列里做。用Redis的List或RabbitMQ做队列。批量处理攒够一批记忆再统一做评分和摘要减少LLM调用次数。本地小模型用Ollama跑一个7B模型专门做记忆处理不走外部API延迟从秒级降到百毫秒级。我现在的配置是工作记忆同步写Redis10ms情景记忆和语义记忆异步写Qdrant后台队列处理。Agent侧感知到的写入延迟基本可以忽略。5.4 记忆冲突导致Agent行为不一致用户先说“用MySQL”后说“改用PostgreSQL”如果两条记忆都被检索出来Agent可能随机选一个。解决方法是冲突消解 时间优先。在检索结果重排序时对于同一主题的记忆只保留最新的那条。具体实现是在payload里加一个topic字段检索后按topic分组每组取timestamp最大的。另外在System Prompt里也要加一句“当记忆中存在冲突信息时以时间最新的为准。”双保险。5.5 MCP连接超时或工具调用失败MCP Server和Agent之间的连接问题常见原因Stdio传输如果Agent和MCP Server在同一台机器用Stdio传输最简单但要注意不要往stdout打日志会污染协议数据。日志走stderr。SSE传输跨机器时用SSE注意CORS配置和心跳间隔。心跳太短浪费资源太长容易断连。30秒比较合适。Token过期如果MCP Server前面有网关做鉴权注意Token刷新机制。Agent侧要能处理401并自动重试。我踩过最坑的一次MCP Server里用console.log打调试信息结果Agent收到的JSON里混入了日志文本解析直接失败。后来所有日志都改成console.error问题消失。5.6 记忆存储膨胀过快跑了一周后发现Qdrant里存了几十万条记忆检索越来越慢。解决定期归档写一个定时任务每天凌晨把30天未访问的记忆移到冷存储比如S3或本地文件从Qdrant里删除。去重写入前先做相似度检查如果与已有记忆的相似度超过0.95直接合并而不是新增。压缩对同一任务的多个记忆片段定期做一次汇总压缩把10条相关记忆合并成1条摘要。我现在设的阈值是单集合超过10万条就触发归档相似度0.92以上触发合并。跑了一个月存储量稳定在5万条左右检索延迟保持在50ms以内。6. 一些实操心得与扩展思路这套系统跑通之后我发现最有价值的不是技术实现而是记忆策略的调优。同样的代码重要性评分阈值调一下、检索权重改一下Agent的表现差异巨大。我建议你在自己的场景里先跑一周收集日志看看哪些记忆被频繁检索、哪些从未被访问然后针对性调整。另外记忆的可解释性很重要。当Agent做出一个决策时你应该能追溯它是基于哪条记忆做出的。我在recall接口里加了一个explain参数返回结果时附带每条记忆的检索分数和命中原因。调试时非常有用。扩展方向的话我目前在尝试的是跨Agent记忆共享。多个Agent协作时能不能共享同一套记忆系统初步想法是用namespace隔离不同Agent的私有记忆同时有一个共享层存放公共知识。这个还在实验阶段等跑稳了再分享。还有一个值得关注的方向是记忆的主动遗忘。现在是被动归档未来可以让Agent自己判断“这条记忆已经没用了主动忘掉”。这需要Agent对自身任务有更强的元认知能力目前还在探索。最后分享一个小技巧在Docker Compose里给memory-service加一个healthcheck配合restart: unless-stopped能避免很多因为服务启动顺序导致的连接失败问题。具体配置healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3 start_period: 40s这个start_period很关键给服务足够的启动时间避免刚启动就被判定为不健康。我一开始没设这个Docker在服务还没初始化完就开始检查一直重启排查了半天才发现问题。
1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词我脑子里蹦出来的不是词典里的“事后聪明”而是开车时那面后视镜。你往前开眼睛盯着前方路况但真正让你敢变道、敢超车的是后视镜里那几秒前的画面。Agent Memory这件事本质上就是在给LLM驱动的智能体装一面足够聪明的后视镜——让它记得刚才发生了什么从而决定下一步怎么走。这个项目标题“hindsight”放在Agent Memory的语境下指向非常明确构建一套面向LLM Agent的记忆管理系统。它要解决的问题很具体——当前大多数Agent在单轮对话或短任务里表现不错一旦任务链条拉长、交互轮次变多就开始“失忆”。你上一轮告诉它“用Python 3.11别用3.12”下一轮它给你生成一个3.12的依赖安装命令。你前面说“数据库用PostgreSQL”后面它给你写MySQL的DDL。这不是模型笨是它根本没有一个可靠的机制把关键信息存下来、在需要的时候取出来。“hindsight”这个命名本身就带着一种设计哲学记忆不是简单的日志堆积而是对过去经验的重新审视和选择性提取。就像人回忆事情你不是把过去每一秒都回放一遍而是根据当前问题从记忆里捞出最相关的片段。这套系统要做的就是让Agent具备这种“按需回忆”的能力。适合谁来参考这篇内容如果你正在做LLM应用开发尤其是涉及多轮对话、长任务编排、工具调用链路的场景那Agent Memory是你绕不过去的坎。如果你只是调用API做单轮问答那暂时用不上。但只要你开始碰MCP协议、开始让Agent调用外部工具、开始处理超过10轮以上的交互记忆管理就会从“锦上添花”变成“不做不行”。我见过太多项目在Demo阶段惊艳一上生产就崩核心原因之一就是记忆没管好。用户说“帮我订明天去上海的机票”Agent查了航班用户说“要上午的”Agent又查了一遍用户说“还是上次那个航空公司”Agent直接懵了——“上次”是哪次没有记忆就没有上下文连续性就没有真正的智能。2. Agent Memory的核心设计思路与方案选型2.1 为什么传统RAG不够用很多人第一反应是记忆嘛不就是把历史对话存进向量数据库用的时候检索一下这个思路对了一半但远远不够。传统RAG面向的是静态知识库文档不变查询模式相对固定。Agent Memory面对的是动态交互流每一轮对话都在产生新信息而且这些信息的“重要性”差异极大。举个例子。用户说“你好”和用户说“我的API Key是sk-xxx请记住”这两句话在向量空间里的距离可能差不多但对Agent来说后者必须被精确记住前者可以丢弃。传统RAG的相似度检索没法区分这种“重要性权重”。你需要一套更精细的记忆管理机制。我在实际项目里踩过的坑早期版本把所有对话历史一股脑塞进向量库结果检索时经常捞出一堆“好的”“明白了”“继续”这种废话真正关键的信息反而被淹没了。后来引入记忆分层才解决这个问题。2.2 记忆分层的设计逻辑“hindsight”这套思路里记忆至少分三层第一层工作记忆Working Memory。这是Agent当前正在处理的任务上下文容量有限通常就是最近几轮对话加上当前任务的状态变量。它相当于人的“短期记忆”容量小但访问极快。实现上一般就是直接放在Prompt的上下文窗口里或者用一个结构化的状态对象来维护。第二层情景记忆Episodic Memory。这是对过去交互事件的记录包括每次任务的目标、执行过程、结果、用户反馈。它相当于人的“经历记忆”——你记得上周做过一个类似的项目但具体细节可能模糊了。实现上通常用向量数据库存储配合时间戳和任务标签做过滤。第三层语义记忆Semantic Memory。这是从多次交互中提炼出来的通用知识和偏好。比如“这个用户偏好用Python而不是JavaScript”“这个项目的数据库规范是PostgreSQL”。它相当于人的“常识和技能记忆”不依赖具体场景可以跨任务复用。实现上可以用键值对存储或者用轻量级的知识图谱。这三层的读写策略完全不同。工作记忆是高频读写情景记忆是写多读少语义记忆是低频写、高频读。如果你用同一套存储机制处理所有层性能和维护都会出问题。2.3 为什么选择MCP作为集成协议MCPModel Context Protocol在这套架构里扮演的是“记忆总线”的角色。Agent需要调用记忆服务时不是直接连数据库而是通过MCP协议暴露的接口来操作。这样做的好处有几个第一解耦。记忆服务的实现可以独立演进Agent不需要关心底层用的是Redis还是PostgreSQL还是向量库。第二标准化。MCP定义了工具调用的统一格式记忆的读写、检索、更新都可以封装成标准的ToolAgent通过Function Calling来触发。第三可观测。所有记忆操作都经过MCP层方便打日志、做审计、排查问题。我试过不用MCP直接让Agent调数据库结果是代码里到处散落着SQL和向量检索逻辑改一个字段要动好几个地方。后来统一走MCP记忆服务的接口稳定了Agent侧的代码干净了很多。2.4 Docker在其中的角色Docker解决的是“环境一致性”问题。Agent Memory系统通常涉及多个组件向量数据库、关系型数据库、缓存、MCP Server、Agent运行时。如果每个组件都手动装光是版本兼容就能耗掉一整天。用Docker Compose编排一条命令拉起全套环境换台机器也能复现。而且记忆服务往往需要持久化存储Docker Volume可以很好地管理数据卷。你不需要担心容器重启后数据丢失也不需要手动配置数据目录权限。对于开发和测试阶段这种便利性尤其重要。3. 核心细节解析与实操要点3.1 记忆的写入策略什么该记什么该忘这是整个系统里最难的部分。记太多检索时噪声大记太少关键信息丢失。我的经验是采用基于规则的过滤 基于重要性的评分双机制。规则层面以下几类信息必须写入情景记忆用户明确表达的偏好“我喜欢用TypeScript”任务的关键约束“预算不超过5000”工具调用的结果摘要“查询到3个航班”错误和异常“API返回429触发限流”以下几类信息可以丢弃或降权纯确认性回复“好的”“收到”重复信息用户第三次说“用Python”与当前任务无关的闲聊重要性评分可以用一个轻量级的LLM来做让模型对每轮对话打一个1-5分低于阈值的直接不进长期记忆。这个评分Prompt我调了好几版核心是让模型判断“如果未来Agent需要回忆这轮对话它有多大概率会用到这条信息”。注意不要用同一个LLM既做Agent推理又做记忆评分容易产生偏差。最好用一个小模型比如7B级别专门做记忆管理大模型专注任务执行。3.2 记忆的检索策略怎么捞到对的信息检索不是简单的向量相似度Top-K。我实际用下来混合检索效果最好向量相似度 关键词匹配 时间衰减 任务标签过滤。具体来说检索分数可以这样算final_score 0.5 * vector_similarity 0.2 * keyword_match 0.2 * recency_score 0.1 * task_relevance其中recency_score用指数衰减越近的记忆分数越高。task_relevance根据当前任务类型和记忆的任务标签做匹配。这个权重不是拍脑袋定的我做过A/B测试。纯向量检索的命中率大概60%加上关键词和时间衰减后能到80%左右。任务标签过滤在跨任务场景下提升最明显因为不同任务的记忆混在一起时标签能有效隔离噪声。还有一个技巧检索时返回原始文本而不是摘要。早期我为了节省Token把记忆压缩成摘要再存结果检索出来的摘要丢失了关键细节。后来改成存原始文本摘要双份检索用摘要做粗筛返回时给原始文本效果好很多。3.3 记忆的更新与遗忘机制记忆不是只增不减的。你需要一套遗忘机制否则存储会无限膨胀检索质量也会下降。我的做法是时间衰减超过30天未被访问的情景记忆自动降权或归档。冲突消解当新记忆与旧记忆冲突时比如用户先说“用MySQL”后说“改用PostgreSQL”保留新的旧的标记为“已废弃”但不删除以备追溯。容量上限每层记忆设一个上限超过后按重要性评分淘汰最低的。这里有个坑不要直接删除记忆。你永远不知道未来会不会需要回溯。标记为“归档”或“低优先级”就够了物理删除是不可逆的。3.4 MCP Tool的设计要点把记忆操作封装成MCP Tool时接口设计要遵循“粗粒度”原则。不要暴露insert_memory、update_memory、delete_memory这种细粒度操作给Agent而是提供remember、recall、forget三个高层接口。remember接收一段文本和可选的元数据任务标签、重要性内部自动决定存哪层、怎么存。recall接收查询文本和可选的过滤条件返回排序后的记忆列表。forget接收记忆ID或查询条件执行归档或降权。这样做的好处是Agent不需要理解记忆系统的内部结构只需要知道“我要记住这个”“我要回忆那个”。接口越简单Agent用错的概率越低。4. 实操过程与核心环节实现4.1 环境准备Docker Compose编排全套服务先上docker-compose.yml的核心配置。这套配置我在Ubuntu 22.04和macOS上都跑过Windows下用WSL2也没问题。version: 3.8 services: vector-db: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - ./data/qdrant:/qdrant/storage environment: - QDRANT__SERVICE__GRPC_PORT6334 cache: image: redis:7-alpine ports: - 6379:6379 volumes: - ./data/redis:/data command: redis-server --appendonly yes memory-service: build: ./memory-service ports: - 8080:8080 depends_on: - vector-db - cache environment: - QDRANT_URLhttp://vector-db:6333 - REDIS_URLredis://cache:6379 - LLM_API_KEY${LLM_API_KEY} volumes: - ./data/memory:/app/data mcp-server: build: ./mcp-server ports: - 3000:3000 depends_on: - memory-service environment: - MEMORY_SERVICE_URLhttp://memory-service:8080这里选Qdrant做向量库是因为它的过滤功能比较强支持在向量检索的同时做payload过滤正好适合我们“向量标签”的混合检索需求。Redis用来做工作记忆的缓存读写延迟低。memory-service是核心业务逻辑mcp-server是对外暴露的MCP接口。提示如果你在Windows上遇到“Virtualization support not detected”导致Docker Desktop起不来先去BIOS里确认VT-x/AMD-V已开启然后在Windows功能里勾选“虚拟机平台”和“适用于Linux的Windows子系统”。这两个都开了还不行就检查Hyper-V是否被其他软件占用。4.2 记忆服务的核心代码实现memory-service用Python FastAPI写核心是三个模块写入、检索、更新。写入模块的关键逻辑async def remember(content: str, metadata: dict): # 第一步重要性评分 importance await score_importance(content) if importance 0.3: return {status: skipped, reason: low_importance} # 第二步判断记忆层级 if metadata.get(type) preference: layer semantic elif metadata.get(task_id): layer episodic else: layer working # 第三步生成摘要和向量 summary await summarize(content) vector await embed(content) # 第四步写入对应存储 if layer working: await redis.setex( fworking:{metadata[session_id]}, 3600, json.dumps({content: content, summary: summary}) ) elif layer episodic: await qdrant.upsert( collection_nameepisodic, points[{ id: generate_id(), vector: vector, payload: { content: content, summary: summary, task_id: metadata[task_id], timestamp: time.time(), importance: importance } }] ) elif layer semantic: await qdrant.upsert( collection_namesemantic, points[{ id: generate_id(), vector: vector, payload: { content: content, summary: summary, category: metadata.get(category, general), timestamp: time.time() } }] ) return {status: ok, layer: layer, importance: importance}检索模块的核心是混合评分async def recall(query: str, filters: dict None, top_k: int 5): query_vector await embed(query) # 向量检索 vector_results await qdrant.search( collection_nameepisodic, query_vectorquery_vector, limittop_k * 3, query_filterbuild_filter(filters) ) # 关键词检索用Redis的全文搜索或简单的倒排索引 keyword_results await keyword_search(query, filters) # 合并去重 merged merge_results(vector_results, keyword_results) # 重排序 scored [] for item in merged: recency math.exp(-0.01 * (time.time() - item[timestamp]) / 86400) task_rel 1.0 if filters and item.get(task_id) filters.get(task_id) else 0.5 final (0.5 * item[vector_score] 0.2 * item[keyword_score] 0.2 * recency 0.1 * task_rel) scored.append((final, item)) scored.sort(keylambda x: x[0], reverseTrue) return [item for _, item in scored[:top_k]]更新模块处理冲突消解async def update_memory(memory_id: str, new_content: str): old await get_memory(memory_id) # 检查是否冲突 conflict await check_conflict(old[content], new_content) if conflict: # 旧记忆标记为废弃 await qdrant.set_payload( collection_nameepisodic, payload{status: deprecated, deprecated_at: time.time()}, points[memory_id] ) # 写入新记忆 await remember(new_content, old[metadata]) else: # 无冲突则合并 merged await merge_content(old[content], new_content) await qdrant.set_payload( collection_nameepisodic, payload{content: merged, updated_at: time.time()}, points[memory_id] )4.3 MCP Server的接口暴露MCP Server用Node.js写核心是把memory-service的HTTP接口转成MCP Tool。这里用官方SDKimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server({ name: hindsight-memory, version: 1.0.0 }, { capabilities: { tools: {} } }); server.setRequestHandler(tools/list, async () ({ tools: [ { name: remember, description: 记住一段信息用于后续回忆, inputSchema: { type: object, properties: { content: { type: string, description: 要记住的内容 }, type: { type: string, enum: [preference, fact, event] }, task_id: { type: string, description: 关联的任务ID } }, required: [content] } }, { name: recall, description: 回忆与查询相关的信息, inputSchema: { type: object, properties: { query: { type: string, description: 查询内容 }, task_id: { type: string, description: 限定任务范围 }, top_k: { type: number, default: 5 } }, required: [query] } }, { name: forget, description: 遗忘指定的记忆, inputSchema: { type: object, properties: { memory_id: { type: string }, query: { type: string } } } } ] })); server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name remember) { const result await fetch(http://memory-service:8080/remember, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(args) }); return { content: [{ type: text, text: JSON.stringify(await result.json()) }] }; } if (name recall) { const result await fetch(http://memory-service:8080/recall, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(args) }); return { content: [{ type: text, text: JSON.stringify(await result.json()) }] }; } // forget类似 }); const transport new StdioServerTransport(); await server.connect(transport);4.4 Agent侧的集成方式Agent侧通过MCP客户端连接这个Server然后在System Prompt里加入记忆使用的指引你拥有记忆能力。在以下情况下调用remember工具 - 用户表达了明确的偏好或约束 - 任务产生了关键结果或错误 - 你判断这条信息在未来对话中可能被用到 在以下情况下调用recall工具 - 用户提到“之前”“上次”“刚才”等指代词 - 当前任务需要参考历史决策 - 你不确定某个信息是否已经确认过 不要每轮对话都调用recall只在确实需要历史信息时调用。这个Prompt我迭代了七八版核心是让Agent知道“什么时候该记什么时候该回忆”。太频繁调用会拖慢响应速度太稀疏又起不到作用。实测下来平均每3-5轮对话触发一次记忆操作是比较合理的频率。5. 常见问题与排查技巧实录5.1 记忆检索返回不相关结果这是最常见的问题。排查思路按优先级来排查项可能原因解决方法向量模型嵌入模型不适合当前语言或领域换用多语言模型或领域微调模型分块策略记忆块太大或太小调整分块大小通常256-512 token较合适过滤条件标签过滤太严或太松检查task_id和category的匹配逻辑权重配置向量相似度权重过高降低向量权重提高关键词和时间权重数据质量记忆里混入了噪声检查重要性评分阈值是否太低我遇到过一次典型情况用户问“之前那个配置怎么写的”检索出来的全是“好的”“收到”这类确认性回复。原因是重要性评分模块的阈值设成了0.1几乎什么都往里存。调到0.3之后噪声明显减少。5.2 Docker容器间网络不通memory-service连不上vector-db报“Connection refused”。排查步骤确认两个服务在同一个Docker网络里。docker-compose默认会创建一个bridge网络所有服务都在里面。检查服务名是否写对。在容器里用ping vector-db测试注意不是localhost。检查端口。Qdrant的HTTP端口是6333gRPC是6334别搞混。检查防火墙。宿主机防火墙一般不影响容器间通信但如果你改了Docker的网络配置可能需要额外放行。提示在memory-service容器里执行curl http://vector-db:6333/healthz如果能返回OK说明网络没问题问题在应用层。5.3 记忆写入延迟高每次remember都要调LLM做重要性评分和摘要生成延迟自然高。优化方案异步写入Agent调用remember后立即返回实际写入在后台队列里做。用Redis的List或RabbitMQ做队列。批量处理攒够一批记忆再统一做评分和摘要减少LLM调用次数。本地小模型用Ollama跑一个7B模型专门做记忆处理不走外部API延迟从秒级降到百毫秒级。我现在的配置是工作记忆同步写Redis10ms情景记忆和语义记忆异步写Qdrant后台队列处理。Agent侧感知到的写入延迟基本可以忽略。5.4 记忆冲突导致Agent行为不一致用户先说“用MySQL”后说“改用PostgreSQL”如果两条记忆都被检索出来Agent可能随机选一个。解决方法是冲突消解 时间优先。在检索结果重排序时对于同一主题的记忆只保留最新的那条。具体实现是在payload里加一个topic字段检索后按topic分组每组取timestamp最大的。另外在System Prompt里也要加一句“当记忆中存在冲突信息时以时间最新的为准。”双保险。5.5 MCP连接超时或工具调用失败MCP Server和Agent之间的连接问题常见原因Stdio传输如果Agent和MCP Server在同一台机器用Stdio传输最简单但要注意不要往stdout打日志会污染协议数据。日志走stderr。SSE传输跨机器时用SSE注意CORS配置和心跳间隔。心跳太短浪费资源太长容易断连。30秒比较合适。Token过期如果MCP Server前面有网关做鉴权注意Token刷新机制。Agent侧要能处理401并自动重试。我踩过最坑的一次MCP Server里用console.log打调试信息结果Agent收到的JSON里混入了日志文本解析直接失败。后来所有日志都改成console.error问题消失。5.6 记忆存储膨胀过快跑了一周后发现Qdrant里存了几十万条记忆检索越来越慢。解决定期归档写一个定时任务每天凌晨把30天未访问的记忆移到冷存储比如S3或本地文件从Qdrant里删除。去重写入前先做相似度检查如果与已有记忆的相似度超过0.95直接合并而不是新增。压缩对同一任务的多个记忆片段定期做一次汇总压缩把10条相关记忆合并成1条摘要。我现在设的阈值是单集合超过10万条就触发归档相似度0.92以上触发合并。跑了一个月存储量稳定在5万条左右检索延迟保持在50ms以内。6. 一些实操心得与扩展思路这套系统跑通之后我发现最有价值的不是技术实现而是记忆策略的调优。同样的代码重要性评分阈值调一下、检索权重改一下Agent的表现差异巨大。我建议你在自己的场景里先跑一周收集日志看看哪些记忆被频繁检索、哪些从未被访问然后针对性调整。另外记忆的可解释性很重要。当Agent做出一个决策时你应该能追溯它是基于哪条记忆做出的。我在recall接口里加了一个explain参数返回结果时附带每条记忆的检索分数和命中原因。调试时非常有用。扩展方向的话我目前在尝试的是跨Agent记忆共享。多个Agent协作时能不能共享同一套记忆系统初步想法是用namespace隔离不同Agent的私有记忆同时有一个共享层存放公共知识。这个还在实验阶段等跑稳了再分享。还有一个值得关注的方向是记忆的主动遗忘。现在是被动归档未来可以让Agent自己判断“这条记忆已经没用了主动忘掉”。这需要Agent对自身任务有更强的元认知能力目前还在探索。最后分享一个小技巧在Docker Compose里给memory-service加一个healthcheck配合restart: unless-stopped能避免很多因为服务启动顺序导致的连接失败问题。具体配置healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3 start_period: 40s这个start_period很关键给服务足够的启动时间避免刚启动就被判定为不健康。我一开始没设这个Docker在服务还没初始化完就开始检查一直重启排查了半天才发现问题。
