基于MCP与Docker构建LLM Agent长期记忆系统实战

1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词我脑子里蹦出来的不是词典释义而是过去半年在Agent项目里反复踩坑的画面。Hindsight直译是“后见之明”放在Agent Memory这个语境下它指向的其实是一个很朴素但极其关键的问题当一个大模型驱动的Agent完成了一轮任务之后它能不能记住自己刚才做了什么、为什么这么做、结果是好是坏并且在下一轮任务里用上这些经验这个问题听起来简单做起来要命。我见过太多Agent项目第一轮对话表现惊艳第三轮就开始“失忆”第五轮直接把前面确认过的约束条件全忘了。用户说“我刚才不是说了不要用红色吗”Agent一脸无辜地回“好的请问您想要什么颜色”。这不是模型能力不够而是记忆架构没设计好。“hindsight”这个项目标题结合热搜词里的agent memory、LLM、MCP、Docker我判断它要解决的核心场景是为LLM Agent构建一套可持久化、可检索、可推理的长期记忆系统并且通过MCP协议对外暴露能力用Docker做标准化部署。说白了就是让Agent拥有“回头看”的能力——不只是记住事实还要记住经验、教训和上下文。这套东西适合谁如果你正在做Agent应用发现模型在多轮交互中表现不稳定如果你在用Dify、Coze这类平台但觉得内置记忆不够用如果你想通过MCP把记忆能力标准化地接入各种LLM客户端——那这篇内容就是写给你的。我会从架构设计、核心原理、Docker部署、MCP接入、常见坑五个维度把“hindsight”这类Agent Memory系统的完整实现路径拆开讲清楚。2. Agent Memory的核心架构不只是存聊天记录2.1 为什么传统RAG不够用很多人一提到Agent记忆第一反应就是“上RAG”。把历史对话向量化存进向量数据库下次检索相似内容拼进Prompt。这个方案能跑通Demo但放到生产环境很快会暴露三个致命问题。第一个问题是时间维度缺失。向量检索本质上是语义相似度匹配它不关心“这件事是先发生的还是后发生的”。用户上周说“预算控制在5000以内”这周说“预算可以放宽到8000”如果两条记录都被检索出来模型很可能取错。传统RAG没有时间衰减和版本覆盖机制。第二个问题是经验无法沉淀。Agent执行了一个任务成功了或者失败了这个“成功/失败”的信号如果只是作为一条普通对话记录存着下次遇到类似任务时模型无法自动提取出“上次这么做失败了这次要换一种方式”。这需要结构化的经验存储而不是扁平的文本向量。第三个问题是检索粒度太粗。一整轮对话可能包含多个意图、多个约束、多个决策点向量化之后变成一个稠密向量检索时要么全中要么全不中。真正有用的记忆系统需要支持细粒度的记忆单元比如“用户偏好”“任务约束”“工具调用结果”“失败原因”分开存储和检索。“hindsight”这类系统的设计思路本质上是在RAG之上加了两层一层是结构化记忆层一层是反思推理层。结构化记忆层负责把对话拆解成不同类型的记忆单元反思推理层负责在任务完成后生成“经验总结”供后续检索使用。2.2 记忆的三种类型与存储策略我在实际项目中把Agent记忆分成三类这个分类方式和“hindsight”的设计理念高度吻合。第一类是工作记忆Working Memory。这是当前会话的上下文窗口生命周期最短通常就是最近N轮对话。它的作用是维持对话连贯性让Agent知道“刚才聊到哪了”。工作记忆一般直接放在Prompt里不需要向量化但需要做Token预算管理。热搜词里提到的“agent 存储 working memory”就是这个层面的问题。我的经验是工作记忆不要超过模型上下文窗口的30%留足空间给系统提示、工具定义和检索到的长期记忆。第二类是情景记忆Episodic Memory。这是跨会话的历史交互记录包括用户说了什么、Agent做了什么、调用了哪些工具、结果如何。情景记忆需要持久化存储通常用关系型数据库存结构化字段用向量数据库存语义索引。检索时既要考虑语义相似度也要考虑时间新鲜度。我一般会给每条情景记忆打三个分数语义相关分、时间衰减分、重要性分加权求和后取Top-K。第三类是语义记忆Semantic Memory。这是从多次交互中抽象出来的规律和偏好比如“这个用户喜欢简洁的回答”“这个项目的代码风格是PEP8”“调用某个API时经常超时需要加重试”。语义记忆不是原始对话而是经过反思生成的“知识”。它的更新频率低但价值密度高。热搜词里的“llm ontology”和“llm wiki”其实就是在探讨如何构建这种结构化知识。三类记忆的关系可以用一个类比理解工作记忆是“你现在手里拿着的文件”情景记忆是“你电脑里的历史文档”语义记忆是“你脑子里总结出来的工作方法”。一个成熟的Agent Memory系统必须同时管理这三层并且支持它们之间的流转——比如从情景记忆中提炼出语义记忆或者根据语义记忆调整工作记忆的检索策略。2.3 MCP协议在记忆系统中的角色MCPModel Context Protocol是Anthropic推出的一个开放协议目的是标准化LLM与外部工具、数据源的交互方式。热搜词里有人问“mcp是软件协议还是硬件协议”这里明确一下MCP是软件协议不是硬件协议。它定义了一套基于JSON-RPC的通信规范让LLM客户端比如Claude Desktop、Cursor、各种IDE插件能够以统一的方式调用外部服务。把Agent Memory做成MCP Server好处非常明显。第一解耦。记忆系统独立部署不绑定特定的LLM框架Dify能用Coze能用自己写的Agent也能用。第二标准化。MCP定义了Resources、Tools、Prompts三种能力记忆的读写、检索、反思可以分别封装成不同的Tool客户端按需调用。第三可组合。一个Agent可以同时接入多个MCP Server记忆Server负责记忆浏览器Server负责网页操作数据库Server负责查询各司其职。我在实际项目里用MCP封装记忆系统时一般会暴露这几个Toolstore_memory写入记忆、retrieve_memory检索记忆、reflect_on_task任务后反思、get_user_profile获取用户画像。每个Tool的输入输出都定义严格的Schema这样LLM客户端能自动生成调用参数减少手写Prompt的工作量。3. 核心细节解析记忆的写入、检索与反思3.1 记忆写入怎么把对话拆成有用的单元记忆写入不是简单地把对话文本存进数据库。如果只是存原文检索时要么召回太多无关内容要么漏掉关键信息。我的做法是在写入阶段就做结构化拆解。具体流程是这样的当一轮对话结束或者一个任务完成系统会触发一个“记忆提取”流程。这个流程本身也是用LLM做的Prompt大概长这样你是一个记忆提取器。请分析以下对话提取出所有值得长期记住的信息并按以下JSON格式输出 { facts: [{content: ..., confidence: 0.9, source: user}], preferences: [{content: ..., scope: global/project, confidence: 0.8}], constraints: [{content: ..., expires_at: 2025-12-31, priority: high}], task_outcomes: [{task: ..., result: success/failure, reason: ...}], tool_insights: [{tool: ..., observation: ..., suggestion: ...}] }这个Prompt的关键在于分类。事实、偏好、约束、任务结果、工具洞察这五类信息的生命周期和检索策略完全不同。事实类记忆需要高置信度才写入偏好类记忆需要标注作用域约束类记忆需要设置过期时间任务结果和工具洞察是反思的原料。我踩过的一个坑是早期版本把所有信息都当成“事实”存结果检索时经常把用户随口说的一句“今天天气不错”也召回出来浪费Token还干扰模型判断。后来加了置信度阈值和分类过滤检索准确率明显提升。另一个细节是去重和冲突处理。用户可能在不同时间说了矛盾的话比如先说“用Python”后说“还是用Go吧”。系统需要检测到这种冲突并且以最新信息为准同时保留旧信息作为历史版本。我的做法是给每条记忆加一个valid_from和valid_until字段检索时只取当前有效的版本。3.2 记忆检索多路召回与重排序检索是记忆系统最核心也最容易出问题的环节。我见过太多项目写入做得很好检索一塌糊涂导致Agent要么“失忆”要么“记忆错乱”。我的检索策略是三路召回重排序。第一路是向量召回。把查询文本向量化在向量数据库里找语义最相似的Top-50条记忆。这一路负责“语义相关”。第二路是关键词召回。用BM25或者简单的倒排索引找包含查询关键词的记忆。这一路负责“精确匹配”弥补向量检索对专有名词、数字、代码标识符不敏感的缺陷。第三路是时间召回。取最近N条记忆不管语义是否相关。这一路负责“新鲜度”确保Agent不会忘记刚刚发生的事情。三路召回的结果合并后用一个重排序模型可以是小型的Cross-Encoder也可以直接用LLM打分做精排。重排序的评分维度包括语义相关度、时间衰减、重要性权重、记忆类型匹配度。最后取Top-10注入Prompt。这里有个关键参数时间衰减系数。我一般用指数衰减半衰期设为7天。也就是说一条7天前的记忆时间得分是今天记忆的一半。这个参数可以根据业务场景调整客服场景可能半衰期是1天个人助理场景可能是30天。还有一个容易被忽略的点是检索结果的格式化。检索出来的记忆不能直接拼成一段文本扔给模型需要标注来源、时间、置信度。我通常这样格式化[记忆检索结果] - [2025-05-10, 置信度0.95, 用户偏好] 用户偏好使用TypeScript而不是JavaScript - [2025-05-08, 置信度0.80, 任务结果] 上次调用支付API时超时重试3次后成功 - [2025-05-01, 置信度0.90, 约束] 项目预算上限8000元有效期至2025-06-30这样模型能清楚地知道每条记忆的“分量”在决策时合理权衡。3.3 反思机制让Agent从经验中学习反思是“hindsight”这个名字最直接的体现。没有反思Agent只是记住了发生了什么有了反思Agent才能从发生的事情中提炼出“下次该怎么做”。我的反思流程通常在任务完成后触发分三步走。第一步是结果评估。判断任务是否成功成功的话关键因素是什么失败的话根因是什么。这一步可以用规则比如工具调用是否返回错误码也可以用LLM判断比如“用户是否表达了满意”。第二步是经验提取。从成功或失败中提炼出可复用的经验。比如“调用某个API时如果返回429等待2秒后重试成功率更高”或者“用户对长文本回答的满意度低于短文本回答”。第三步是记忆更新。把提取出的经验写入语义记忆同时调整相关情景记忆的权重。如果某条情景记忆被证明是导致失败的原因降低它的检索优先级如果某条经验被多次验证有效提高它的置信度。反思的Prompt设计很关键。我一般会要求LLM输出结构化的反思结果{ task_summary: 为用户生成了一份销售报告, outcome: success, key_factors: [使用了用户偏好的图表类型, 数据源选择了最新的季度数据], lessons: [ {lesson: 用户偏好柱状图而非饼图, confidence: 0.85, scope: user_preference}, {lesson: 季度数据比月度数据更受用户认可, confidence: 0.70, scope: project_knowledge} ], memory_adjustments: [ {memory_id: xxx, action: increase_weight, reason: 被验证有效} ] }反思的频率需要控制。每轮对话都反思会消耗大量Token而且很多对话没有反思价值。我的策略是任务型对话完成后必反思闲聊型对话每10轮反思一次或者当检测到用户情绪明显变化时触发反思。4. Docker部署实战从零搭建记忆服务4.1 环境准备与镜像选择“hindsight”这类记忆系统通常包含多个组件API服务、向量数据库、关系型数据库、缓存。用Docker Compose编排是最省心的方式。热搜词里大量出现docker安装、docker compose、windows安装docker说明很多读者卡在环境准备这一步。我先把这块讲透。Windows用户建议直接装Docker Desktop但要注意两个坑。第一个坑是虚拟化支持。如果启动时报“virtualization support not detected”需要进BIOS开启VT-x或AMD-V然后在Windows功能里启用“虚拟机平台”和“适用于Linux的Windows子系统”。第二个坑是WSL2后端。Docker Desktop默认用WSL2如果WSL没装好Docker起不来。管理员权限运行wsl --install重启后再装Docker Desktop。Linux用户直接用官方脚本安装Docker Engine和Docker Compose Plugin。注意不要用apt install docker.io那个版本太老Compose V2不支持。镜像选择上我推荐这套组合组件镜像用途API服务自构建基于python:3.11-slim记忆读写、反思逻辑向量库qdrant/qdrant:latest语义检索关系库postgres:16-alpine结构化记忆存储缓存redis:7-alpine工作记忆、会话状态反向代理caddy:2-alpineHTTPS、MCP Server暴露选Qdrant而不是Milvus或Weaviate原因是Qdrant的Docker镜像小、启动快、Python客户端成熟对于中小规模记忆系统完全够用。Postgres选alpine版本镜像只有几十MB。Redis用来存工作记忆和会话锁避免多实例并发写冲突。4.2 docker-compose.yml完整配置下面是我实际在用的Compose配置做了精简但保留了核心结构version: 3.9 services: memory-api: build: ./api ports: - 8000:8000 environment: - DATABASE_URLpostgresql://memory:memorypostgres:5432/memory - QDRANT_URLhttp://qdrant:6333 - REDIS_URLredis://redis:6379/0 - OPENAI_API_KEY${OPENAI_API_KEY} - EMBEDDING_MODELtext-embedding-3-small depends_on: postgres: condition: service_healthy qdrant: condition: service_started redis: condition: service_started restart: unless-stopped postgres: image: postgres:16-alpine environment: - POSTGRES_USERmemory - POSTGRES_PASSWORDmemory - POSTGRES_DBmemory volumes: - pg_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U memory] interval: 5s timeout: 5s retries: 5 qdrant: image: qdrant/qdrant:latest volumes: - qdrant_data:/qdrant/storage ports: - 6333:6333 redis: image: redis:7-alpine command: redis-server --appendonly yes volumes: - redis_data:/data caddy: image: caddy:2-alpine ports: - 443:443 - 80:80 volumes: - ./Caddyfile:/etc/caddy/Caddyfile - caddy_data:/data depends_on: - memory-api volumes: pg_data: qdrant_data: redis_data: caddy_data:几个关键点解释一下。depends_on里的condition: service_healthy确保Postgres完全启动后再启动API避免连接被拒。Qdrant和Redis不需要健康检查因为它们启动很快。Caddy用来做HTTPS终止和反向代理MCP Server需要HTTPS才能被某些客户端接入。4.3 数据库初始化与索引优化Postgres启动后需要建表。我一般用Alembic做迁移但为了简化这里直接给SQLCREATE TABLE memories ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), type VARCHAR(32) NOT NULL, content TEXT NOT NULL, embedding_id VARCHAR(64), confidence FLOAT DEFAULT 0.8, importance FLOAT DEFAULT 0.5, scope VARCHAR(64) DEFAULT global, source VARCHAR(32), valid_from TIMESTAMPTZ DEFAULT NOW(), valid_until TIMESTAMPTZ, created_at TIMESTAMPTZ DEFAULT NOW(), metadata JSONB DEFAULT {} ); CREATE INDEX idx_memories_type ON memories(type); CREATE INDEX idx_memories_scope ON memories(scope); CREATE INDEX idx_memories_valid ON memories(valid_from, valid_until); CREATE INDEX idx_memories_metadata ON memories USING GIN(metadata);Qdrant的Collection创建时要注意向量维度。如果用text-embedding-3-small维度是1536。创建Collection的Python代码from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams client QdrantClient(urlhttp://localhost:6333) client.create_collection( collection_nameagent_memory, vectors_configVectorParams(size1536, distanceDistance.COSINE), )Qdrant的Payload里存memory_id、type、scope、valid_until检索时可以用Filter做预过滤比如只检索typepreference且valid_until为空的记忆。这样能大幅减少向量检索的候选集提升速度。4.4 启动与验证配置写好后docker compose up -d启动。第一次启动会拉镜像视网络情况可能需要几分钟。启动完成后用docker compose ps检查所有服务状态确保都是running或healthy。验证API是否正常curl -X POST http://localhost:8000/memory \ -H Content-Type: application/json \ -d {type:fact,content:用户偏好深色主题,confidence:0.9}返回201就说明写入成功。再调检索接口curl http://localhost:8000/memory/search?q主题偏好limit5能看到刚才写入的记忆就说明向量化和检索链路通了。注意如果Qdrant连接失败检查QDRANT_URL是否用了服务名qdrant而不是localhost。Docker Compose内部服务之间用服务名通信localhost指向容器自身。5. MCP接入让记忆能力标准化输出5.1 MCP Server的实现要点把记忆系统封装成MCP Server核心是实现MCP协议定义的几个方法。MCP基于JSON-RPC 2.0Server需要响应initialize、tools/list、tools/call等请求。我用Python的mcp库来实现核心代码结构from mcp.server import Server from mcp.types import Tool, TextContent app Server(hindsight-memory) app.list_tools() async def list_tools(): return [ Tool( namestore_memory, description存储一条长期记忆, inputSchema{ type: object, properties: { type: {type: string, enum: [fact, preference, constraint, outcome]}, content: {type: string}, confidence: {type: number, default: 0.8} }, required: [type, content] } ), Tool( nameretrieve_memory, description检索相关记忆, inputSchema{ type: object, properties: { query: {type: string}, limit: {type: integer, default: 5} }, required: [query] } ), Tool( namereflect_on_task, description任务完成后进行反思, inputSchema{ type: object, properties: { task_description: {type: string}, outcome: {type: string, enum: [success, failure]}, details: {type: string} }, required: [task_description, outcome] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name store_memory: result await memory_service.store(**arguments) return [TextContent(typetext, textf已存储ID: {result[id]})] elif name retrieve_memory: memories await memory_service.search(**arguments) formatted \n.join([f- [{m[type]}] {m[content]} for m in memories]) return [TextContent(typetext, textformatted)] elif name reflect_on_task: lessons await reflection_service.reflect(**arguments) return [TextContent(typetext, textlessons)]这个Server可以通过stdio或SSE两种方式暴露。stdio适合本地客户端如Claude DesktopSSE适合远程接入。我一般用SSE配合Caddy做HTTPS这样任何支持MCP的客户端都能连。5.2 客户端接入配置以Claude Desktop为例配置文件在~/Library/Application Support/Claude/claude_desktop_config.jsonMac或%APPDATA%\Claude\claude_desktop_config.jsonWindows{ mcpServers: { hindsight-memory: { url: https://your-domain.com/mcp/sse, headers: { Authorization: Bearer your-token } } } }如果是Cursor或VS Code插件配置方式类似在MCP设置里填Server URL和认证信息。热搜词里有人问“codex无法找到mcp”和“codex接入figma mcp怎么授权”这类问题的通用排查思路是先确认MCP Server是否正常响应initialize请求再确认客户端配置的URL和认证信息是否正确最后看客户端日志里有没有JSON-RPC错误。大部分“找不到MCP”的问题要么是Server没启动要么是URL路径写错了。5.3 与Dify、Coze等平台的集成Dify从1.0版本开始支持MCP可以在“工具”里添加自定义MCP Server。配置方式和Claude Desktop类似填URL和认证头即可。Coze的支持稍弱一些但可以通过HTTP节点间接调用记忆API。如果平台不支持MCP也可以直接调REST API。我在API层同时暴露了REST和MCP两套接口REST给传统平台用MCP给新客户端用。两套接口共享同一套业务逻辑只是协议适配层不同。提示MCP Server的认证一定要做。我见过有人把MCP Server暴露在公网且不加认证结果被扫描到之后记忆库被清空。至少加一个Bearer Token有条件的话上mTLS。6. 常见问题与排查技巧实录6.1 记忆检索不准的排查思路检索不准是最常见的问题表现是Agent要么答非所问要么重复问已经确认过的信息。排查按以下顺序来。先看写入是否正常。查Postgres里有没有对应的记忆记录Qdrant里有没有对应的向量点。如果写入缺失检查记忆提取的Prompt是否过于严格导致很多信息被过滤掉了。再看向量化是否一致。写入时用的Embedding模型和检索时用的必须是同一个。我踩过一次坑写入用text-embedding-ada-002检索用text-embedding-3-small维度一样但向量空间不同检索结果完全乱套。后来在配置里强制统一模型问题解决。然后看检索参数是否合理。limit设太小会漏召回设太大引入噪声。我的经验值是工作记忆场景limit5任务规划场景limit10反思场景limit20。时间衰减系数也要根据场景调客服场景衰减快知识管理场景衰减慢。最后看重排序是否有效。如果重排序模型太弱三路召回的结果可能被错误排序。可以先用简单的加权求和语义分×0.6 时间分×0.3 重要性×0.1做基线再逐步引入Cross-Encoder。6.2 Docker环境下的网络与存储问题Docker环境最常见的问题是网络不通。表现是API容器连不上Postgres或Qdrant。排查步骤进API容器docker exec -it memory-api sh然后ping postgres和ping qdrant。如果不通检查Compose里是否在同一个网络。默认情况下Compose会创建一个共享网络所有服务都在里面。如果手动指定了network_mode: host服务之间反而不能用服务名通信。另一个问题是数据丢失。如果没配Volume容器重启后数据全没。Compose里一定要给Postgres、Qdrant、Redis都配named volume。我见过有人用bind mount挂到Windows目录结果权限问题导致Postgres起不来。Windows下建议用named volume不要用bind mount。还有资源限制。Qdrant和Postgres都比较吃内存如果Docker Desktop默认内存分配太小比如2GB服务会频繁OOM。建议给Docker Desktop至少分配4GB内存生产环境8GB起步。6.3 常见问题速查表现象可能原因排查方法解决方案Agent失忆检索未召回查检索日志的Top-K结果调大limit降低时间衰减记忆冲突旧记忆未失效查valid_until字段写入新记忆时使旧记忆失效写入失败Embedding API超时查API容器日志加重试机制换本地Embedding模型MCP连接失败URL或认证错误用curl测MCP端点检查配置确认Server启动Docker启动失败虚拟化未开启查Docker Desktop日志BIOS开VT-x装WSL2检索太慢向量库未索引查Qdrant Collection状态建HNSW索引加Payload过滤Token超限记忆注入太多统计Prompt Token数限制注入条数压缩记忆内容6.4 几个我踩过的坑和对应技巧坑一反思过度导致记忆污染。早期版本每轮对话都反思结果LLM生成了一堆低质量的“经验”比如“用户喜欢被称呼为‘您’”这种没有实际价值的记忆反而干扰了检索。后来加了置信度阈值低于0.7的反思结果不写入和人工审核队列质量明显提升。坑二工作记忆和长期记忆边界模糊。一开始我把所有对话都往长期记忆里写导致检索时召回大量无关的闲聊内容。后来明确只有包含事实、偏好、约束、任务结果的对话才写入长期记忆纯闲聊只保留在工作记忆里会话结束就丢弃。坑三MCP Server的SSE连接不稳定。SSE是长连接网络抖动会导致断连。我在Caddy里配了flush_interval -1和read_timeout 300s同时在客户端加了自动重连逻辑。如果对稳定性要求极高可以考虑用stdio方式本地部署不走网络。坑四多用户记忆隔离。如果系统服务多个用户记忆必须按用户隔离。我的做法是在Postgres和Qdrant里都加user_id字段检索时强制过滤。MCP Server的认证Token里携带user_id避免客户端伪造。7. 记忆系统的扩展方向与个人体会这套架构跑通之后可以往几个方向扩展。一个是记忆的可视化做一个Web界面让用户能看到Agent记住了什么、检索了什么、反思了什么增加透明度和可控性。另一个是记忆的导入导出支持从其他Agent平台迁移记忆或者把记忆导出成结构化知识库。还有一个是多Agent共享记忆多个Agent共用一个记忆池但通过权限控制读写范围适合团队协作场景。我个人在实际操作中的体会是Agent Memory这个领域工程复杂度远高于算法复杂度。核心的向量检索、LLM反思都不难难的是怎么设计数据模型让记忆不冲突、怎么调检索参数让召回准确、怎么控制成本让Token不爆炸、怎么保证多用户隔离和安全。这些东西没有标准答案只能根据具体场景反复调。最后分享一个小技巧给记忆加“热度”字段。每次记忆被检索到并且被Agent实际使用比如影响了回答内容热度加一。热度高的记忆在后续检索中加权热度低的逐渐降权。这个简单的机制能让系统自动淘汰无用记忆效果比定期清理好得多。我用了三个月记忆库从最初的几千条稳定在几百条高价值记忆检索准确率和响应速度都明显提升。