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而不是自己写一套APIMCPModel 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 记忆遗忘不是所有东西都值得记住这一点很多人忽略。记忆系统如果只写不删向量库会膨胀检索精度会下降而且会引入过时信息。我设计了一个简单的遗忘策略记忆类型保留策略触发条件工作记忆会话结束即清除会话关闭情景记忆保留30天定时任务扫描语义记忆永久保留但降权超过90天未命中权重乘0.8低置信度记忆7天内未确认则删除定时任务扫描注意遗忘策略一定要可配置不同场景差异很大。做法律咨询的Agent和做闲聊的Agent记忆保留周期完全不是一个量级。4. 实操过程从零搭建一套hindsight记忆系统4.1 环境准备与Docker Compose编排我假设你用的是Linux或者macOSWindows的话建议用WSL2Docker 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( namestore_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( namerecall_memory, description根据查询检索相关记忆, inputSchema{ type: object, properties: { query: {type: string}, top_k: {type: integer, default: 5}, memory_type: {type: string} }, required: [query] } ), Tool( namerun_hindsight, description对指定会话执行后见之明提炼, inputSchema{ type: object, properties: { session_id: {type: string} }, required: [session_id] } ) ]run_hindsight这个工具是整个系统的灵魂。它的逻辑是拉取指定session的所有episodic记忆拼成对话记录调用LLM做提炼把结果写入semantic记忆库同时给原始episodic打上processedtrue的标记。# 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 processedfalse 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( modelgpt-4o-mini, messages[{role: user, content: HINDSIGHT_PROMPT.format(dialoguedialogue)}], 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 processedtrue, needs_reviewtrue 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_namesemantic_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 processedtrue 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-small1536维每百万token成本很低。如果要做多语言nomic-embed-text768维支持100语言。向量维度直接影响存储和检索速度。以10万条记忆为例模型维度存储占用单次检索延迟Top-5text-embedding-3-small1536~600MB~15msBGE-M3768~300MB~8msnomic-embed-text768~300MB~8msQdrant默认用余弦相似度如果你的嵌入模型输出已经归一化用点积会更快。我实测下来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排查步骤打开任务管理器性能标签页看CPU的“虚拟化”是否显示“已启用”。如果是“已禁用”进BIOS开启Intel VT-x或AMD-V。如果BIOS里开了但还是报错检查Windows功能里“Hyper-V”和“虚拟机平台”是否勾选。如果用的是WSL2后端确认WSL2内核已更新wsl --update。某些安全软件会拦截虚拟化临时关闭试试。注意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(typetext, textjson.dumps(result))就没问题了。5.4 记忆检索不准召回率高但精度低这是记忆系统最核心的调优问题。我的排查清单现象可能原因解决方向召回一堆无关记忆嵌入模型不适合当前语言/领域换模型或做微调相关记忆排在后位缺少重排序加交叉编码器同一事实重复召回去重逻辑缺失写入时做相似度去重过时信息被召回遗忘策略未生效检查定时任务和权重衰减检索结果不稳定向量未归一化统一做L2归一化实操心得我建议在检索层加一个“记忆新鲜度”的加权。具体做法是最终得分 相似度得分 × 时间衰减因子。时间衰减因子用指数衰减半衰期设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任务但对你监控系统健康度非常有用。我把它挂在定时任务里每天推一次报告心里有数。
基于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而不是自己写一套APIMCPModel 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 记忆遗忘不是所有东西都值得记住这一点很多人忽略。记忆系统如果只写不删向量库会膨胀检索精度会下降而且会引入过时信息。我设计了一个简单的遗忘策略记忆类型保留策略触发条件工作记忆会话结束即清除会话关闭情景记忆保留30天定时任务扫描语义记忆永久保留但降权超过90天未命中权重乘0.8低置信度记忆7天内未确认则删除定时任务扫描注意遗忘策略一定要可配置不同场景差异很大。做法律咨询的Agent和做闲聊的Agent记忆保留周期完全不是一个量级。4. 实操过程从零搭建一套hindsight记忆系统4.1 环境准备与Docker Compose编排我假设你用的是Linux或者macOSWindows的话建议用WSL2Docker 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( namestore_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( namerecall_memory, description根据查询检索相关记忆, inputSchema{ type: object, properties: { query: {type: string}, top_k: {type: integer, default: 5}, memory_type: {type: string} }, required: [query] } ), Tool( namerun_hindsight, description对指定会话执行后见之明提炼, inputSchema{ type: object, properties: { session_id: {type: string} }, required: [session_id] } ) ]run_hindsight这个工具是整个系统的灵魂。它的逻辑是拉取指定session的所有episodic记忆拼成对话记录调用LLM做提炼把结果写入semantic记忆库同时给原始episodic打上processedtrue的标记。# 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 processedfalse 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( modelgpt-4o-mini, messages[{role: user, content: HINDSIGHT_PROMPT.format(dialoguedialogue)}], 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 processedtrue, needs_reviewtrue 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_namesemantic_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 processedtrue 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-small1536维每百万token成本很低。如果要做多语言nomic-embed-text768维支持100语言。向量维度直接影响存储和检索速度。以10万条记忆为例模型维度存储占用单次检索延迟Top-5text-embedding-3-small1536~600MB~15msBGE-M3768~300MB~8msnomic-embed-text768~300MB~8msQdrant默认用余弦相似度如果你的嵌入模型输出已经归一化用点积会更快。我实测下来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排查步骤打开任务管理器性能标签页看CPU的“虚拟化”是否显示“已启用”。如果是“已禁用”进BIOS开启Intel VT-x或AMD-V。如果BIOS里开了但还是报错检查Windows功能里“Hyper-V”和“虚拟机平台”是否勾选。如果用的是WSL2后端确认WSL2内核已更新wsl --update。某些安全软件会拦截虚拟化临时关闭试试。注意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(typetext, textjson.dumps(result))就没问题了。5.4 记忆检索不准召回率高但精度低这是记忆系统最核心的调优问题。我的排查清单现象可能原因解决方向召回一堆无关记忆嵌入模型不适合当前语言/领域换模型或做微调相关记忆排在后位缺少重排序加交叉编码器同一事实重复召回去重逻辑缺失写入时做相似度去重过时信息被召回遗忘策略未生效检查定时任务和权重衰减检索结果不稳定向量未归一化统一做L2归一化实操心得我建议在检索层加一个“记忆新鲜度”的加权。具体做法是最终得分 相似度得分 × 时间衰减因子。时间衰减因子用指数衰减半衰期设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任务但对你监控系统健康度非常有用。我把它挂在定时任务里每天推一次报告心里有数。
