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

1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”“hindsight”这个词本身很有意思字面意思是“事后的洞察力”也就是我们常说的“后见之明”。放在LLM Agent的语境里它指向一个非常具体且要命的问题Agent的记忆机制。你如果搭过稍微复杂一点的Agent一定遇到过这种场景——用户第一轮说“帮我查一下北京明天的天气”Agent调了天气API返回了结果第二轮用户说“那后天呢”Agent一脸茫然因为它根本不知道“那”指的是什么也不知道上一轮查的是哪个城市。这不是模型不够聪明而是它没有“后视镜”看不到自己刚刚做过什么。hindsight这个项目标题结合热搜词里的agent memory、LLM、MCP、Docker我判断它要解决的核心问题就是为LLM Agent构建一套可持久化、可检索、可推理的记忆系统让Agent在多轮对话、跨会话、跨任务场景下能够“回头看”从而做出更连贯、更准确的决策。这件事为什么现在特别重要因为Agent正在从“单次问答玩具”变成“长期驻留的生产力工具”。你让它帮你管理项目进度它得记住上周的里程碑你让它做客服它得记住用户三天前投诉过什么你让它做代码助手它得记住这个仓库的架构决策。没有记忆Agent永远是个“金鱼脑”每次对话都是从零开始。适合谁来读这篇内容如果你正在做Agent应用开发或者你在用MCP协议搭建工具链又或者你单纯想搞清楚“Agent记忆到底该怎么设计”那这篇东西就是写给你的。我会从架构思路、核心细节、实操落地、踩坑排查四个维度把hindsight这类Agent记忆系统的里里外外讲透。2. 整体设计与思路拆解Agent记忆不是“存个向量”就完事2.1 为什么传统RAG方案撑不起Agent记忆很多人一提到“给LLM加记忆”第一反应就是上向量数据库把对话历史embedding一下存进去下次检索top-k。这个方案在简单场景下能跑但放到Agent记忆里很快就会崩。原因在于Agent记忆和普通RAG有本质区别。普通RAG是“静态知识检索”你问一个问题它从文档库里找相关段落。Agent记忆是“动态经验管理”它要处理的是谁在什么时间做了什么、结果如何、这个结果对后续决策有什么影响。这里面有时间维度、因果维度、状态维度单纯靠向量相似度根本表达不了。举个例子。用户说“把那个文件删了”。向量检索可能找到三天前用户提到过“项目A的配置文件”。但Agent需要知道的是三天前用户说“项目A的配置文件先别动”昨天用户说“项目A已经归档了”。这两条信息结合起来才能判断“那个文件”到底能不能删。向量相似度检索不出这种时序逻辑。所以hindsight这类项目的核心设计思路一定是分层记忆架构而不是单一向量库。2.2 分层记忆架构Working Memory、Episodic Memory、Semantic Memory我在实际项目中总结下来Agent记忆至少要分三层第一层Working Memory工作记忆。这是当前会话的短期上下文相当于人的“意识焦点”。它保存最近几轮对话、当前任务状态、临时变量。这一层通常直接放在prompt里或者用滑动窗口管理。特点是容量小、读写快、会话结束就丢弃或归档。第二层Episodic Memory情景记忆。这是跨会话的“事件日志”。每一次用户交互、每一次工具调用、每一次Agent决策都作为一条“情景”存下来。每条情景包含时间戳、参与者、动作、参数、结果、情绪标签如果有。这一层是Agent“回头看”的主要数据源。第三层Semantic Memory语义记忆。这是从情景中抽象出来的“事实和规则”。比如从多次“用户不喜欢冗长回复”的情景中抽象出“该用户偏好简洁输出”这条语义记忆。这一层通常用知识图谱或结构化存储支持推理和冲突检测。hindsight这个命名我猜测它的重点在第二层和第三层——因为“hindsight”强调的就是从历史情景中提取洞察。热搜词里出现的a-memguard: a proactive defense framework for llm-based agent memory也印证了这一点记忆系统不仅要存还要有防御机制防止错误记忆污染Agent行为。2.3 MCP协议在记忆系统中的角色热搜词里MCP出现频率极高还有mcp协议、playwright mcp、unity mcp、同花顺mcp等等。MCPModel Context Protocol本质上是一个标准化工具调用协议它让LLM能够以统一的方式访问外部资源。在Agent记忆系统里MCP的价值在于把记忆的读写操作标准化成MCP工具。比如定义memory_store、memory_retrieve、memory_forget三个MCP工具任何支持MCP的Agent框架都能直接调用不需要为每个框架单独写适配层。这解决了一个大问题记忆系统的可移植性。你今天用LangChain搭Agent明天想换AutoGPT记忆层不用重写因为MCP协议把接口统一了。这也是为什么hindsight这类项目通常会选择MCP作为对外接口。2.4 Docker化部署为什么记忆系统必须容器化热搜词里Docker、docker安装、docker desktop、docker网络不通这些词扎堆出现说明这个项目的部署方式大概率是Docker化的。Agent记忆系统Docker化有几个硬性理由依赖隔离记忆系统通常要同时跑向量库如Qdrant、图数据库如Neo4j、缓存如Redis、应用服务。这些组件的依赖版本经常打架Docker能彻底隔离。持久化卷管理记忆数据是核心资产必须用Docker Volume做持久化容器重启数据不丢。网络配置标准化记忆系统内部组件之间需要稳定通信Docker Compose能定义清晰的网络拓扑避免docker网络不通这种经典问题。一键复现你分享一个docker-compose.yml别人就能跑起一套完整的记忆系统这对开源项目来说太重要了。我实测下来用Docker Compose编排记忆系统是最稳的方案。下面会详细讲怎么配。3. 核心细节解析与实操要点记忆的写入、检索与遗忘3.1 记忆写入不是所有对话都值得存新手最容易犯的错就是把所有对话历史一股脑全存进记忆库。结果就是检索时噪声极大Agent被无关信息干扰性能反而下降。hindsight这类系统通常会有记忆写入策略我总结了几条实用规则规则一只存“有决策价值”的交互。用户说“你好”不用存用户说“以后所有报告都用PDF格式”必须存。判断标准是这条信息是否会影响未来的行为。规则二情景记忆要带元数据。每条记忆至少包含timestamp、session_id、user_id、action_type、content、importance_score。importance_score可以用LLM打分也可以用规则比如包含“记住”“以后”“总是”等关键词的加分。规则三写入前做去重和冲突检测。如果新记忆和旧记忆矛盾比如用户先说“喜欢红色”后说“讨厌红色”不能简单覆盖要标记冲突并保留时间线。热搜词里的a-memguard就是干这个的——主动防御错误记忆。实操上写入流程可以这样设计# 伪代码示意基于常见Agent记忆实践 def write_memory(interaction): # 1. LLM判断是否值得存 if not llm_judge_importance(interaction): return # 2. 提取结构化字段 memory { timestamp: now(), session_id: interaction.session_id, content: interaction.summary, entities: extract_entities(interaction), importance: llm_score_importance(interaction) } # 3. 冲突检测 conflicts detect_conflicts(memory) if conflicts: mark_conflict(memory, conflicts) # 4. 写入向量库图数据库 vector_db.insert(memory) graph_db.insert_relations(memory)注意importance_score的阈值不要设太高否则会漏掉关键信息也不要设太低否则记忆库膨胀太快。我一般设0.6左右然后根据实际效果微调。3.2 记忆检索三个关键维度“我是谁、我在找什么、我能提供什么”热搜词里有一条特别有意思llm的token三个点key我是谁、query我在找什么、value我能提供什么。这其实是在说记忆检索的query构造要包含三个要素Key我是谁当前Agent的身份、角色、权限。不同角色的Agent能访问的记忆范围不同。Query我在找什么当前任务的目标、上下文、关键词。Value我能提供什么检索到的记忆能如何帮助当前决策。传统向量检索只用了Query忽略了Key和Value。hindsight这类系统会把三者结合做多路召回重排序。具体做法向量召回用Query的embedding去向量库找top-50。图召回用Key和Query中的实体去图数据库找关联节点召回top-20。时间召回根据当前时间召回最近N条相关记忆。重排序用一个轻量LLM对合并后的候选集打分按相关性×重要性×时效性排序取top-5注入prompt。这个流程比单纯向量检索复杂但效果提升非常明显。我实测下来多路召回能让Agent在长对话中的准确率提升30%以上。3.3 记忆遗忘不会忘的Agent不是好Agent人的记忆会遗忘Agent的记忆也必须会遗忘。否则记忆库无限膨胀检索效率下降而且旧信息可能已经过时。遗忘策略有三种时间衰减记忆的权重随时间指数衰减超过一定阈值的自动归档或删除。容量限制每类记忆设上限超出时淘汰重要性最低的。主动遗忘用户说“忘掉刚才说的”或者检测到记忆冲突时标记旧记忆为失效。实操心得遗忘策略一定要可配置。不同场景需求不同——客服Agent可能需要保留半年的用户偏好而临时任务Agent可能只需要保留几小时。我一般把遗忘参数放在配置文件里方便调整。3.4 MCP工具定义让记忆系统即插即用如果hindsight对外提供MCP接口那它至少会定义这几个工具工具名功能输入参数输出memory_store写入记忆content, metadata, importancememory_idmemory_retrieve检索记忆query, key, top_k, time_rangememory_listmemory_forget遗忘记忆memory_id 或 conditionsuccessmemory_summarize总结记忆session_id 或 time_rangesummary这样任何支持MCP的Agent框架比如Claude Desktop、Trae IDE等都能直接接入。热搜词里trae ide 搭载 burp suite mcp server、ruoyi-vue-pro合并mcp功能这些说明MCP生态正在快速扩张记忆系统作为MCP Server是非常合理的定位。4. 实操过程与核心环节实现从零搭一套Agent记忆系统4.1 环境准备Docker与Docker Compose安装热搜词里docker安装、docker desktop安装教程、windows安装docker、ubuntu安装docker并运行python环境这些词说明很多读者卡在环境准备这一步。我分别说下Windows和Ubuntu的安装要点。Windows安装Docker Desktop确认系统是Windows 10/11 64位专业版或家庭版都行。开启WSL2在PowerShell里跑wsl --install重启。下载Docker Desktop安装包双击安装勾选“Use WSL 2 instead of Hyper-V”。安装完成后在设置里确认WSL2集成已开启。常见坑如果启动时报virtualization support not detected说明BIOS里虚拟化没开。重启进BIOS找到Intel VT-x或AMD-V设为Enabled。另外docker desktop failed to start because v这类错误多半是WSL2内核版本太旧跑wsl --update更新一下。Ubuntu安装Docker# 卸载旧版本 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install ca-certificates curl gnupg # 添加官方GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证 sudo docker run hello-world注意Ubuntu下非root用户要加docker组sudo usermod -aG docker $USER然后重新登录。否则每次都要sudo很烦。4.2 Docker Compose编排记忆系统下面是一套我实际用过的docker-compose.yml包含向量库、图数据库、缓存和应用服务version: 3.8 services: qdrant: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - qdrant_data:/qdrant/storage networks: - memory_net neo4j: image: neo4j:5 ports: - 7474:7474 - 7687:7687 environment: - NEO4J_AUTHneo4j/password123 volumes: - neo4j_data:/data networks: - memory_net redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis_data:/data networks: - memory_net memory-service: build: ./memory-service ports: - 8000:8000 environment: - QDRANT_URLhttp://qdrant:6333 - NEO4J_URLbolt://neo4j:7687 - REDIS_URLredis://redis:6379 depends_on: - qdrant - neo4j - redis networks: - memory_net volumes: qdrant_data: neo4j_data: redis_data: networks: memory_net: driver: bridge启动命令docker compose up -d。常见坑docker网络不通是高频问题。如果memory-service连不上qdrant先检查是否在同一个network里。用docker compose exec memory-service ping qdrant测试。另外Docker Desktop在Windows下有时候端口映射会抽风重启Docker Desktop能解决大部分问题。4.3 记忆服务核心代码实现记忆服务的核心是三个模块写入、检索、遗忘。我用Python FastAPI写个骨架from fastapi import FastAPI from pydantic import BaseModel from qdrant_client import QdrantClient from neo4j import GraphDatabase import redis import uuid from datetime import datetime app FastAPI() qdrant QdrantClient(urlhttp://qdrant:6333) neo4j_driver GraphDatabase.driver(bolt://neo4j:7687, auth(neo4j, password123)) redis_client redis.from_url(redis://redis:6379) class MemoryInput(BaseModel): content: str session_id: str user_id: str importance: float 0.5 app.post(/memory/store) def store_memory(mem: MemoryInput): memory_id str(uuid.uuid4()) timestamp datetime.utcnow().isoformat() # 写入向量库 qdrant.upsert( collection_nameepisodic_memory, points[{ id: memory_id, vector: get_embedding(mem.content), payload: { content: mem.content, session_id: mem.session_id, user_id: mem.user_id, timestamp: timestamp, importance: mem.importance } }] ) # 写入图数据库 with neo4j_driver.session() as session: session.run( CREATE (m:Memory {id: $id, content: $content, timestamp: $ts}) WITH m MATCH (u:User {id: $uid}) CREATE (u)-[:HAS_MEMORY]-(m), idmemory_id, contentmem.content, tstimestamp, uidmem.user_id ) # 缓存最近记忆 redis_client.lpush(frecent:{mem.session_id}, memory_id) redis_client.ltrim(frecent:{mem.session_id}, 0, 99) return {memory_id: memory_id, status: stored} app.get(/memory/retrieve) def retrieve_memory(query: str, user_id: str, top_k: int 5): # 向量召回 vector_results qdrant.search( collection_nameepisodic_memory, query_vectorget_embedding(query), limittop_k * 3, query_filter{must: [{key: user_id, match: {value: user_id}}]} ) # 时间召回 recent_ids redis_client.lrange(frecent:{user_id}, 0, top_k) # 合并重排序简化版 candidates {r.id: r for r in vector_results} for rid in recent_ids: if rid not in candidates: # 从qdrant补取 pass # 按重要性×时效性排序 sorted_results sorted( candidates.values(), keylambda x: x.payload[importance] * time_decay(x.payload[timestamp]), reverseTrue )[:top_k] return {memories: [r.payload for r in sorted_results]}这个骨架跑起来后你就可以用MCP协议把它包装成工具供Agent调用。4.4 MCP Server封装把上面的HTTP接口包装成MCP Server核心是定义工具描述# mcp_server.py 示意 from mcp.server import Server, Tool server Server(hindsight-memory) server.tool() def memory_store(content: str, session_id: str, user_id: str, importance: float 0.5): 存储一条Agent记忆。当用户提供重要信息、偏好或决策时调用。 # 调用上面的HTTP接口 return requests.post(http://localhost:8000/memory/store, json{...}).json() server.tool() def memory_retrieve(query: str, user_id: str, top_k: int 5): 检索相关记忆。在需要回忆历史交互或用户偏好时调用。 return requests.get(http://localhost:8000/memory/retrieve, params{...}).json() server.tool() def memory_forget(memory_id: str): 遗忘指定记忆。当用户要求删除信息或检测到冲突时调用。 return requests.delete(fhttp://localhost:8000/memory/{memory_id}).json()这样任何支持MCP的客户端都能通过标准协议访问记忆系统。热搜词里playwright mcp、chrome devtools mcp、browser use mcp这些都是MCP生态的典型应用记忆系统作为MCP Server是完全对路的。5. 常见问题与排查技巧实录5.1 记忆检索不准召回了一堆无关内容这是最常见的问题。排查思路现象可能原因解决方案召回内容与query无关embedding模型不适合中文/领域换用领域微调的embedding模型召回内容重复写入时没去重写入前做相似度检测0.95的合并召回内容过时没有时间衰减加入时间衰减因子旧记忆降权召回内容矛盾没有冲突检测引入a-memguard类防御机制实操心得embedding模型的选择比向量库的选择重要得多。我试过用通用模型和领域模型检索准确率能差一倍。中文场景建议用BGE或M3E系列英文场景可以用OpenAI的text-embedding-3。5.2 Docker容器启动失败docker desktop failed to start because v这类错误90%是虚拟化或WSL2问题。排查步骤确认BIOS虚拟化已开。跑wsl --status看WSL2是否正常。跑wsl --update更新内核。Docker Desktop设置里Resources → WSL Integration确认对应发行版已开启。实在不行重置Docker Desktop到出厂设置。Ubuntu下如果docker网络不通检查防火墙sudo ufw status必要时sudo ufw allow 6333等端口。5.3 记忆库膨胀太快如果发现记忆库几天就涨到几个G说明写入策略太宽松。解决方案提高importance_score阈值。对短于一定长度的交互直接丢弃。定期跑归档任务把超过30天的低重要性记忆移到冷存储。用Redis做最近记忆缓存向量库只存摘要。5.4 Agent不调用记忆工具有时候Agent明明有记忆工具但就是不调用。原因通常是工具描述不够清晰。MCP工具的description要写得让LLM一看就知道什么时候用。比如不要写“存储记忆”要写“当用户提供个人信息、偏好设置或重要决策时调用此工具存储以便后续对话中回忆”。另外可以在system prompt里明确指示“在回答用户问题前先调用memory_retrieve检索相关历史。”6. 记忆系统的扩展方向与个人体会这套架构跑通之后扩展空间很大。比如可以加记忆摘要层定期用LLM把零散情景记忆压缩成高层语义记忆减少检索噪声。也可以加记忆共享层让多个Agent共享部分记忆适合多Agent协作场景。还可以加记忆可视化用图数据库的前端把记忆关系画出来方便调试。我个人在实际操作中的体会是Agent记忆系统的难点不在技术而在策略。存什么、怎么存、什么时候忘、怎么检索这些策略决定了系统的上限。技术选型反而是次要的Qdrant还是MilvusNeo4j还是Nebula差距没有想象中那么大。最后分享一个小技巧调试记忆系统时先把top_k设大一点比如20观察召回结果再逐步缩小。同时打开详细日志记录每次检索的query、召回内容、最终注入prompt的内容。这样出问题时能快速定位是召回阶段还是重排序阶段的问题。