基于MCP与Docker的LLM Agent记忆系统：hindsight后见之明实践

1. 从“hindsight”说起：为什么Agent的记忆问题值得单独拎出来做

“hindsight”这个词本身很有意思，字面意思是“事后的洞察力”，也就是我们常说的“后见之明”。放在LLM Agent的语境里，它指向一个非常具体且要命的问题：Agent在完成任务之后，能不能回过头来审视自己走过的路，把有用的经验留下来，把没用的噪音清出去？

我接触过不少做Agent项目的团队，大家一开始都把精力砸在工具调用、提示词工程、多轮对话编排上，等到系统跑了一段时间，用户开始抱怨“它怎么又忘了上次说的”“同一个错误犯了三遍”“前面确认过的信息后面又搞混了”，才意识到记忆层没搭好。Agent memory不是一个锦上添花的功能模块，它直接决定了Agent能不能从“一次性问答机器”变成“持续协作伙伴”。

这个项目标题“hindsight”加上agent memory、LLM、MCP、Docker这几个关键词，基本可以勾勒出一个典型场景：用Docker容器化部署一套面向LLM Agent的记忆管理系统，通过MCP协议与Agent框架对接，让Agent具备对历史交互进行回溯、提炼和结构化存储的能力。它解决的核心问题是：Agent的working memory（工作记忆）容量有限、上下文窗口昂贵、长期记忆检索不准。适合谁看？如果你正在做Agent应用开发，或者你已经在用Claude Desktop、Trae IDE这类支持MCP的工具，想给自己的Agent加一层“记得住、找得回、用得对”的记忆能力，那这篇内容就是给你写的。

我下面会从整体设计思路、核心细节、实操部署、问题排查几个维度，把这件事拆开讲透。不是理论综述，是我自己踩过坑之后整理出来的可复现方案。

2. 整体设计思路：为什么是MCP加Docker加记忆分层

2.1 为什么选MCP而不是自己写一套API

MCP（Model Context Protocol）这两年被讨论得很多，但很多人对它的理解还停留在“又一个协议”的层面。我用下来最直观的感受是：MCP把“Agent怎么发现工具、怎么调用工具、怎么拿回结果”这件事标准化了。在没有MCP之前，你要让Agent访问一个外部记忆库，得自己写function calling的schema，每个框架的格式还不一样，换一个Agent框架就得重写一遍适配层。

MCP的价值在于，你只需要实现一个MCP Server，暴露几个工具方法，比如store_memory、recall_memory、summarize_session，任何支持MCP的客户端都能直接挂载使用。我实测下来，Claude Desktop、Trae IDE、以及一些开源的Agent框架，挂载同一个MCP Server基本不需要改代码，配置里加一行地址就行。

注意：MCP目前有stdio和SSE两种传输方式，本地开发用stdio最省事，跨机器或者容器化部署建议用SSE，但SSE的鉴权要自己处理好，别裸奔。

2.2 Docker在这里扮演什么角色

记忆系统涉及几个组件：向量数据库（存语义记忆）、关系型数据库（存结构化记忆和元数据）、嵌入模型服务（做文本向量化）、MCP Server本身。这些东西如果直接装在宿主机上，版本冲突、端口占用、环境变量污染，折腾一圈下来半天没了。

Docker Compose一把梭的好处是：所有依赖版本锁定，网络隔离，数据卷持久化，换一台机器docker compose up就能复现。我试过在Windows、Linux、macOS上部署同一套配置，除了Docker Desktop的安装差异，compose文件本身完全不用改。

2.3 记忆分层的设计逻辑

Agent的记忆不能是一锅粥。我采用的是三层结构：

• Working Memory（工作记忆）：当前会话的上下文，存在内存或Redis里，生命周期就是一次会话。这一层不追求持久化，追求的是读写快。
• Episodic Memory（情景记忆）：按会话或任务为单位存储的摘要，记录“什么时候、做了什么、结果如何”。存在关系型数据库里，方便按时间范围查询。
• Semantic Memory（语义记忆）：从多次交互中提炼出来的事实、偏好、规则，向量化后存向量数据库，支持语义检索。

hindsight的核心动作发生在第二层到第三层的转化：会话结束后，Agent回头审视这次交互，把值得长期保留的信息提炼出来，写入语义记忆。这就是“后见之明”的技术实现。

3. 核心细节解析：记忆写入、检索与遗忘的实操要点

3.1 记忆写入：什么时候写、写什么、怎么写

写入时机很关键。我见过两种极端：一种是每轮对话都写，结果向量库里全是“好的”“明白了”这种废话；另一种是等会话结束才写，结果会话中途崩溃，什么都没留下。

我的做法是双通道写入：

• 实时通道：每轮对话结束后，把原始对话片段写入episodic memory，只存不提炼，保证不丢数据。
• 异步通道：会话空闲超过一定时间（比如5分钟）或者会话显式结束，触发一次hindsight提炼，把episodic里的内容压缩成semantic memory。

提炼的提示词我改了很多版，最后稳定下来的结构是这样的：

HINDSIGHT_PROMPT = """ 你是一个记忆提炼助手。请审视以下对话记录，提取出值得长期保留的信息。 提取规则： 1. 用户明确表达的偏好、习惯、约束条件 2. 任务执行中验证有效的解决方案 3. 重复出现的错误模式及其修正方法 4. 不要提取：寒暄、临时性确认、与任务无关的闲聊 输出格式（JSON）： { "facts": ["事实1", "事实2"], "preferences": ["偏好1"], "lessons": ["经验教训1"], "confidence": 0.0-1.0 } 对话记录： {dialogue} """

实操心得：confidence字段很有用。低于0.6的提炼结果我建议先存到待审核区，不要直接进语义记忆。我踩过的坑是，早期没有这个阈值，结果Agent把用户随口说的一句“今天天气不错”当成了“用户喜欢晴天”的长期偏好，后面推荐户外活动时疯狂推晴天方案，很尴尬。

3.2 记忆检索：三个点key、query、value的映射

热词里有一条“llm的token三个点key我是谁、query我在找什么、value我能提供什么”，这个说法很形象。在记忆检索场景里：

• Key（我是谁）：当前Agent的身份和角色设定，决定了检索时的过滤条件。比如一个客服Agent和一个编程助手Agent，检索同一批记忆时应该有不同的优先级。
• Query（我在找什么）：当前用户输入经过改写后的检索意图。直接拿原始输入去检索效果往往不好，因为口语化表达和记忆库里的结构化文本之间存在语义鸿沟。
• Value（我能提供什么）：检索到的记忆片段，经过重排序后注入到当前上下文。

我的检索流程是：先用元数据过滤（时间范围、记忆类型、置信度），再做向量相似度检索，最后用交叉编码器重排序。三步下来，Top-3的命中率比单纯向量检索高不少。

3.3 记忆遗忘：不是所有东西都值得记住

这一点很多人忽略。记忆系统如果只写不删，向量库会膨胀，检索精度会下降，而且会引入过时信息。我设计了一个简单的遗忘策略：

注意：遗忘策略一定要可配置，不同场景差异很大。做法律咨询的Agent和做闲聊的Agent，记忆保留周期完全不是一个量级。

4. 实操过程：从零搭建一套hindsight记忆系统

4.1 环境准备与Docker Compose编排

我假设你用的是Linux或者macOS，Windows的话建议用WSL2，Docker Desktop的虚拟化支持问题后面会讲。

目录结构先规划好：

hindsight/ ├── docker-compose.yml ├── .env ├── mcp-server/ │ ├── Dockerfile │ ├── requirements.txt │ └── src/ │ ├── main.py │ ├── memory.py │ └── hindsight.py └── data/ ├── postgres/ └── qdrant/

docker-compose.yml的核心配置：

version: "3.9" services: postgres: image: postgres:16-alpine environment: POSTGRES_USER: ${PG_USER} POSTGRES_PASSWORD: ${PG_PASSWORD} POSTGRES_DB: hindsight volumes: - ./data/postgres:/var/lib/postgresql/data ports: - "5432:5432" healthcheck: test: ["CMD-SHELL", "pg_isready -U ${PG_USER}"] interval: 10s timeout: 5s retries: 5 qdrant: image: qdrant/qdrant:latest volumes: - ./data/qdrant:/qdrant/storage ports: - "6333:6333" - "6334:6334" mcp-server: build: ./mcp-server environment: PG_DSN: postgresql://${PG_USER}:${PG_PASSWORD}@postgres:5432/hindsight QDRANT_URL: http://qdrant:6333 EMBEDDING_MODEL: ${EMBEDDING_MODEL} ports: - "8080:8080" depends_on: postgres: condition: service_healthy qdrant: condition: service_started

提示：PostgreSQL的healthcheck很重要，MCP Server启动时会连数据库，如果数据库没就绪，Server会崩。加上condition: service_healthy能避免这个问题。

4.2 MCP Server的核心实现

MCP Server我用Python写，因为生态最成熟。核心依赖就几个：mcp、asyncpg、qdrant-client、openai（用于调嵌入模型）。

# src/main.py from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncpg from qdrant_client import QdrantClient app = Server("hindsight-memory") @app.list_tools() async def list_tools(): return [ Tool( name="store_memory", description="存储一条记忆到情景记忆库", inputSchema={ "type": "object", "properties": { "session_id": {"type": "string"}, "content": {"type": "string"}, "memory_type": {"type": "string", "enum": ["episodic", "semantic"]} }, "required": ["session_id", "content"] } ), Tool( name="recall_memory", description="根据查询检索相关记忆", inputSchema={ "type": "object", "properties": { "query": {"type": "string"}, "top_k": {"type": "integer", "default": 5}, "memory_type": {"type": "string"} }, "required": ["query"] } ), Tool( name="run_hindsight", description="对指定会话执行后见之明提炼", inputSchema={ "type": "object", "properties": { "session_id": {"type": "string"} }, "required": ["session_id"] } ) ]

run_hindsight这个工具是整个系统的灵魂。它的逻辑是：拉取指定session的所有episodic记忆，拼成对话记录，调用LLM做提炼，把结果写入semantic记忆库，同时给原始episodic打上processed=true的标记。

# src/hindsight.py async def run_hindsight(session_id: str, pg_pool, qdrant, llm_client): rows = await pg_pool.fetch( "SELECT content FROM episodic_memory WHERE session_id=$1 AND processed=false ORDER BY created_at", session_id ) if not rows: return {"status": "no_new_memory"} dialogue = "\n".join([r["content"] for r in rows]) response = await llm_client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": HINDSIGHT_PROMPT.format(dialogue=dialogue)}], response_format={"type": "json_object"} ) result = json.loads(response.choices[0].message.content) if result.get("confidence", 0) < 0.6: await pg_pool.execute( "UPDATE episodic_memory SET processed=true, needs_review=true WHERE session_id=$1", session_id ) return {"status": "low_confidence", "data": result} for fact in result.get("facts", []): vector = await embed(fact) await qdrant.upsert( collection_name="semantic_memory", points=[{ "id": str(uuid.uuid4()), "vector": vector, "payload": {"content": fact, "type": "fact", "session_id": session_id} }] ) await pg_pool.execute( "UPDATE episodic_memory SET processed=true WHERE session_id=$1", session_id ) return {"status": "ok", "extracted": len(result.get("facts", []))}

4.3 与Agent框架的对接配置

MCP Server跑起来之后，在客户端配置里挂载。以Claude Desktop为例，配置文件里加：

{ "mcpServers": { "hindsight": { "command": "docker", "args": ["exec", "-i", "hindsight-mcp-server-1", "python", "-m", "src.main"], "env": {} } } }

如果你用的是SSE方式，配置改成URL形式：

{ "mcpServers": { "hindsight": { "url": "http://localhost:8080/sse" } } }

实操心得：stdio方式在Docker环境下有个坑，docker exec -i需要容器保持运行。我建议MCP Server容器用tail -f /dev/null作为入口命令保持存活，然后通过exec调用具体逻辑。或者直接用SSE，省心很多。

4.4 嵌入模型的选择与参数计算

嵌入模型我试过几个：OpenAI的text-embedding-3-small、BGE-M3、以及本地部署的nomic-embed-text。选型逻辑：

• 如果数据不出内网，用BGE-M3本地部署，768维，中文效果好。
• 如果追求性价比，text-embedding-3-small，1536维，每百万token成本很低。
• 如果要做多语言，nomic-embed-text，768维，支持100+语言。

向量维度直接影响存储和检索速度。以10万条记忆为例：

Qdrant默认用余弦相似度，如果你的嵌入模型输出已经归一化，用点积会更快。我实测下来，10万条量级，Qdrant的单次检索延迟都在20ms以内，完全够用。

5. 常见问题与排查技巧实录

5.1 Docker Desktop启动失败：virtualization support not detected

这是Windows用户最高频的问题。报错信息通常是：

virtualization support not detected docker desktop failed to start because virtualization support is not enabled

排查步骤：

1. 打开任务管理器，性能标签页，看CPU的“虚拟化”是否显示“已启用”。如果是“已禁用”，进BIOS开启Intel VT-x或AMD-V。
2. 如果BIOS里开了但还是报错，检查Windows功能里“Hyper-V”和“虚拟机平台”是否勾选。
3. 如果用的是WSL2后端，确认WSL2内核已更新：wsl --update。
4. 某些安全软件会拦截虚拟化，临时关闭试试。

注意：Windows家庭版默认没有Hyper-V，需要手动安装或者用WSL2后端。我建议直接用WSL2，性能更好，兼容性问题也少。

5.2 Docker网络不通：容器之间互相访问失败

Compose默认会创建一个bridge网络，服务之间用服务名互相访问。如果MCP Server连不上PostgreSQL，先检查：

# 进入mcp-server容器 docker exec -it hindsight-mcp-server-1 sh # 测试DNS解析 ping postgres # 测试端口 nc -zv postgres 5432

如果ping不通，检查compose文件里服务是否在同一个网络下。如果端口不通，检查PostgreSQL是否真的启动了，healthcheck是否通过。

另一个常见坑是：在宿主机上用localhost:5432连容器里的PostgreSQL，需要确认ports映射正确。容器内的5432映射到宿主机的5432，但容器之间通信用的是服务名和容器内端口，不是宿主机端口。

5.3 MCP连接失败：provider rejected the request schema

这个报错通常出现在工具调用的参数schema不匹配时。排查思路：

• 检查inputSchema的required字段是否和实际传入的参数一致。
• 检查参数类型，比如top_k传了字符串"5"而不是整数5。
• 检查MCP Server返回的content格式是否符合协议，必须是[{"type": "text", "text": "..."}]。

我踩过的一个坑是：工具返回了JSON字符串，但没有包在TextContent里，客户端解析失败。后来统一用TextContent(type="text", text=json.dumps(result))就没问题了。

5.4 记忆检索不准：召回率高但精度低

这是记忆系统最核心的调优问题。我的排查清单：

实操心得：我建议在检索层加一个“记忆新鲜度”的加权。具体做法是，最终得分 = 相似度得分 × 时间衰减因子。时间衰减因子用指数衰减，半衰期设30天。这样新记忆天然有优势，老记忆除非特别相关，否则不会挤占Top位置。

5.5 性能瓶颈：写入延迟高

如果每轮对话都同步写入向量库，延迟会累积。我的优化方案：

• 写入走异步队列，用Redis或者内存队列缓冲，后台worker批量写入。
• 批量写入时，Qdrant的upsert支持一次传多个point，比单条写入快一个数量级。
• 嵌入计算可以并行，用asyncio.gather并发调嵌入接口。

实测下来，单条写入从平均80ms降到批量写入的5ms/条，效果很明显。

6. 记忆系统的扩展方向与个人经验

这套hindsight系统跑稳定之后，我陆续加了一些扩展。一个是记忆可视化，用简单的Web界面展示语义记忆库里的内容，支持按时间、类型、置信度筛选，方便人工审核和清理。另一个是跨Agent记忆共享，多个Agent挂载同一个MCP Server，通过namespace隔离，但允许显式共享某些公共记忆。

还有一个我觉得很有价值的方向是记忆冲突检测。当新提炼的事实和已有记忆矛盾时，系统应该标记出来而不是直接覆盖。比如用户先说“我喜欢咖啡”，后来又说“我戒咖啡了”，这两条记忆应该共存，但检索时以时间新的为准，同时保留冲突记录供人工判断。

我个人在实际操作中的体会是：记忆系统的难点不在技术栈，而在“什么值得记”这个判断上。我早期追求大而全，结果向量库里噪音太多，检索质量反而下降。后来把提炼阈值调高，宁缺毋滥，Agent的表现明显更稳定。另外，定期人工审查语义记忆库很有必要，我一般每周花半小时过一遍新增记忆，删掉明显错误的，调整置信度，这个习惯帮我避免了好几次线上事故。

最后分享一个小技巧：在MCP Server里加一个memory_stats工具，返回当前记忆库的总量、各类型占比、平均置信度、最近7天新增数量。这个工具不直接参与Agent任务，但对你监控系统健康度非常有用。我把它挂在定时任务里，每天推一次报告，心里有数。