基于MCP与Docker构建LLM智能体持久化记忆系统hindsight实战

1. 为什么“事后复盘”这件事值得单独做一个项目

做过几年开发或者运维的人都有一个共同的体会：线上出问题的时候，最值钱的东西不是监控面板上那条红色的曲线，而是“上一次遇到类似情况时，我们到底是怎么处理的”。这条经验往往散落在聊天记录、工单系统、某个人的脑子里，甚至是一份已经没人维护的文档里。等到下一次故障来临，所有人又得从头翻一遍日志、重新推演一遍链路。

“hindsight”这个项目标题本身就点明了核心——事后之明。它不是要做实时告警，也不是要做全链路追踪，而是把“事情发生之后才想明白的那些东西”沉淀下来，变成下一次可以主动调用的记忆。结合热词里的 agent memory、LLM、MCP、Docker 来看，这个项目的定位就很清晰了：给基于大语言模型的智能体构建一套可持久化、可检索、可主动防御的记忆系统，并且通过 MCP 协议对外暴露能力，用 Docker 做标准化交付。

我最初接触这个方向是因为一个很具体的痛点：团队里用 LLM 搭了一个运维助手，每次让它分析故障，它都表现得像第一次上班——同样的错误模式，上周刚分析过，这周又问一遍，它完全不记得。你可能会说，把历史对话塞进上下文不就行了？问题是上下文窗口有限，token 成本摆在那里，而且塞进去的噪声越多，模型注意力越分散。所以真正要解决的不是“能不能记住”，而是“记什么、怎么记、什么时候取出来用”。

这套东西适合谁来参考？三类人：一是正在做 LLM 应用、被“记忆”问题卡住的开发者；二是想把内部知识库和智能体打通的运维或平台工程师；三是对 MCP 协议感兴趣、想找一个完整落地案例来练手的技术人。不需要你是算法专家，但得能看懂基本的 Python、会用 Docker、知道什么是 API。下面我按实际搭建的顺序，把设计思路、关键细节、完整实操和踩过的坑一次讲清楚。

2. 整体架构设计与技术选型背后的取舍

2.1 为什么是“记忆”而不是“知识库”

很多人第一反应是把 hindsight 做成一个 RAG 知识库，文档切块、向量化、检索拼接。这条路我试过，问题在于：知识库是静态的、面向文档的，而 agent memory 是动态的、面向交互的。一次故障处理过程中产生的关键信息，往往不是某篇文档里的一句话，而是“当时判断 A 方案不行，因为 B 组件在高并发下会超时”这种带有上下文和决策链路的片段。

所以 hindsight 的记忆单元设计成事件 + 反思的结构。事件是原始记录，反思是事后补充的判断。这跟热词里提到的 “a-memguard: a proactive defense framework for llm-based agent memory” 思路是一致的——记忆不只是存，还要有主动防御，防止错误记忆被反复强化。举个例子，如果某次故障的初步判断是错的，后来纠正了，那这条错误判断必须被标记为“已推翻”，否则下次检索出来会误导模型。

2.2 MCP 协议在这里扮演什么角色

MCP 全称 Model Context Protocol，简单理解就是一套让 LLM 应用和外部工具/数据源对话的标准接口。热词里反复出现 “mcp是什么”“mcp协议”“agent mcp”，说明很多人还在搞明白它到底解决什么问题。我的理解是：在没有 MCP 之前，每接一个工具就要写一套适配代码，工具一多就是灾难。MCP 把这些能力抽象成 server，LLM 侧作为 client 去调用，协议统一了，复用性就上来了。

hindsight 把记忆的读写能力封装成 MCP server，好处是任何支持 MCP 的客户端都能直接调用，不用关心底层是向量库还是关系库。热词里提到的 “playwright mcp”“burpsuite mcp”“blender mcp” 都是同一思路在不同领域的应用。你甚至可以在 Chrome 扩展设置里启用 MCP 连接，让浏览器里的助手直接读写 hindsight 的记忆。

2.3 Docker 化交付的必要性

热词里 “docker安装”“docker desktop”“windows安装docker”“virtualization support not detected” 这些词高频出现，说明环境问题是大家最头疼的。hindsight 依赖向量数据库、嵌入模型服务、MCP server 三四个组件，如果让每个人手动装，光是版本兼容就能劝退一半人。用 Docker Compose 编排，一条命令拉起全部服务，这是最省事的做法。

注意：Windows 上装 Docker Desktop 如果报 “virtualization support not detected”，先去 BIOS 里确认虚拟化技术（Intel VT-x 或 AMD-V）已开启，然后在“启用或关闭 Windows 功能”里勾选 Hyper-V 和“虚拟机平台”。这两步缺一不可，很多人只做了第一步就以为好了。

2.4 技术栈选型对照

选 SQLite 而不是 PostgreSQL，核心考量是降低上手门槛。这个项目定位是个人和小团队用，没必要为了“看起来专业”引入一个需要单独维护的数据库服务。SQLite 配合向量扩展，几万条记忆的检索性能完全够用。等数据量真的上来了，再迁移到 pgvector 也就是改个连接串的事。

3. 核心细节拆解：记忆到底怎么存、怎么取

3.1 记忆单元的数据结构设计

一条记忆记录包含这些字段：唯一 ID、时间戳、事件类型（故障/决策/发现/纠正）、原始内容、嵌入向量、关联标签、置信度、状态（有效/已推翻/待验证）。这里最关键的是置信度和状态两个字段，它们是实现“主动防御”的基础。

置信度是一个 0 到 1 的浮点数，初始记录时由写入方给出。比如运维助手自动记录一条故障分析，置信度可能只有 0.6；人工确认过的结论，置信度可以给到 0.95。检索的时候，置信度低于阈值的记忆会被降权或者直接过滤。状态字段则用来处理“事后发现当初判断错了”的情况——把状态改成“已推翻”，这条记忆就不会再被当作有效参考。

热词里有个很有意思的说法：“llm的token三个点key我是谁、query我在找什么、value我能提供什么”。这其实是在用 key-query-value 的框架理解注意力机制。放到记忆系统里也成立：key 是记忆的标签和类型，query 是当前问题的语义，value 是记忆的具体内容。检索的本质就是拿 query 去匹配 key，然后取出 value。

3.2 写入流程：从原始事件到结构化记忆

写入不是简单地把文本塞进数据库。完整流程是这样的：

1. 接收原始输入：可能是一段对话、一条日志、一个工单描述。
2. 提取关键信息：用 LLM 做一次结构化抽取，识别出事件类型、涉及组件、关键结论。
3. 生成嵌入向量：把结构化后的文本送进嵌入模型，得到向量表示。
4. 计算初始置信度：根据来源可靠性给一个基础分，人工输入高于自动抽取。
5. 查重与合并：检索是否有高度相似的已有记忆，如果有就合并或更新，避免重复。
6. 落库并建立索引：写入 SQLite，同时更新向量索引和关键词索引。

第 5 步的查重很容易被忽略，但不做的话记忆库会迅速膨胀。我实测下来，相似度阈值设在 0.92 左右比较合适，太高会漏掉该合并的，太低会把不同的事情混在一起。

3.3 检索流程：混合检索的具体实现

纯向量检索的问题是，它对精确的关键词不敏感。比如你搜“MySQL 连接池超时”，向量检索可能返回一堆“数据库性能问题”的泛泛记忆，但真正相关的那条可能因为表述不同而排在后面。所以 hindsight 用混合检索：

• 关键词检索：用 SQLite 的全文索引，匹配标签和内容中的精确词。
• 向量检索：计算 query 向量与记忆向量的余弦相似度。
• 融合排序：两路结果按加权分数合并，关键词权重 0.4，向量权重 0.6。

这个权重不是拍脑袋定的。我做过一轮小规模评测，用 50 个真实查询测召回率，0.4/0.6 的组合在精确查询和语义查询上都比较均衡。如果你的场景里专有名词特别多，可以把关键词权重调到 0.5。

3.4 主动防御机制：防止错误记忆污染

这是 hindsight 区别于普通记忆库的地方。防御分三层：

• 写入时校验：置信度低于 0.3 的记忆直接拒绝写入，避免垃圾进垃圾出。
• 检索时降权：置信度 0.3 到 0.6 之间的记忆，检索分数乘以 0.7 的惩罚系数。
• 定期审计：每周跑一次审计任务，把长期未被检索到、且置信度低的记忆标记为“待清理”。

实操心得：审计任务不要自动删除记忆，只做标记。我踩过一次坑，自动清理把一条看似没用的记忆删了，结果两周后正好用到。标记为“待清理”之后人工确认，稳妥得多。

4. 完整实操：从零把 hindsight 跑起来

4.1 环境准备与 Docker 编排

先确认 Docker 可用。Linux 上装 Docker 用官方脚本，Windows 和 macOS 装 Docker Desktop。装完之后跑docker --version和docker compose version确认两个命令都在。

项目目录结构建议这样组织：

hindsight/ ├── docker-compose.yml ├── mcp-server/ │ ├── Dockerfile │ └── src/ ├── embedding/ │ ├── Dockerfile │ └── model/ └── data/ └── memory.db

docker-compose.yml的核心内容：

services: embedding: build: ./embedding ports: - "8001:8001" volumes: - ./embedding/model:/app/model mcp-server: build: ./mcp-server ports: - "8002:8002" volumes: - ./data:/app/data environment: - EMBEDDING_URL=http://embedding:8001 - DB_PATH=/app/data/memory.db depends_on: - embedding

这里有个细节：depends_on只保证启动顺序，不保证 embedding 服务已经就绪。所以 mcp-server 里要做重试逻辑，启动时如果连不上 embedding，等 5 秒再试，最多试 10 次。

4.2 嵌入服务的搭建

嵌入服务用一个轻量级模型，比如 all-MiniLM-L6-v2 这个级别的小模型，CPU 上跑单条推理大概几十毫秒，批量处理更快。用 FastAPI 包一层：

from fastapi import FastAPI from sentence_transformers import SentenceTransformer app = FastAPI() model = SentenceTransformer('/app/model') @app.post("/embed") def embed(texts: list[str]): vectors = model.encode(texts, normalize_embeddings=True) return {"vectors": vectors.tolist()}

normalize_embeddings=True很关键，归一化之后余弦相似度就等价于点积，计算更快。模型文件提前下载好放进model目录，容器启动时直接加载，避免运行时联网下载。

4.3 MCP Server 的核心接口实现

MCP Server 需要暴露几个核心工具：memory_write、memory_search、memory_update_status、memory_audit。用 Python 的 MCP SDK 实现，核心逻辑：

@mcp.tool() def memory_write(content: str, event_type: str, confidence: float, tags: list[str]): if confidence < 0.3: return {"status": "rejected", "reason": "confidence too low"} vector = get_embedding(content) similar = find_similar(vector, threshold=0.92) if similar: merge_memory(similar.id, content, confidence) return {"status": "merged", "id": similar.id} mem_id = insert_memory(content, event_type, confidence, tags, vector) return {"status": "created", "id": mem_id}

memory_search里做混合检索，先分别拿两路结果，再融合排序。这里要注意 SQLite 的全文索引和向量检索是两次独立查询，不要试图用一条 SQL 搞定，分开查再合并反而更清晰。

4.4 参数计算：相似度阈值和权重怎么定

相似度阈值 0.92 这个数不是随便写的。我用一批标注数据测过：真正重复的记忆，余弦相似度普遍在 0.94 以上；相关但不重复的，集中在 0.85 到 0.92 之间；不相关的，基本低于 0.8。所以 0.92 是“合并”和“不合并”的分界线。

混合检索的权重也是类似逻辑。关键词权重 0.4、向量权重 0.6，是因为实测中语义查询占比更高。如果你的记忆库里标签体系很规范，关键词命中率会上升，可以调到 0.5/0.5。这个参数建议做成配置项，不要硬编码。

4.5 启动与验证

docker compose up -d之后，用docker compose logs -f mcp-server看日志。看到 “MCP server listening on 8002” 就说明起来了。然后写一条测试记忆：

curl -X POST http://localhost:8002/tools/memory_write \ -H "Content-Type: application/json" \ -d '{"content":"MySQL连接池超时，调整max_connections后恢复","event_type":"fault","confidence":0.9,"tags":["mysql","连接池"]}'

再搜一下验证：

curl -X POST http://localhost:8002/tools/memory_search \ -H "Content-Type: application/json" \ -d '{"query":"数据库连接问题","top_k":3}'

能返回刚才那条记忆，说明写入和检索链路都通了。

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

5.1 启动类问题速查

5.2 检索质量问题排查

搜不到想要的记忆，先分情况：

• 关键词能搜到、语义搜不到：嵌入模型对领域词汇不敏感，考虑微调或者加关键词权重。
• 语义能搜到、关键词搜不到：标签体系不完善，写入时强制要求打标签。
• 都搜不到：检查记忆是否真的写进去了，置信度是否被过滤了。

踩坑记录：有一次检索一直返回空，查了半天发现是写入时置信度给了 0.25，被写入校验直接拒了，但接口返回的是 200，没仔细看返回体里的 status 字段。后来把接口改成拒绝时返回 400，问题就明显了。

5.3 记忆膨胀的处理

跑了一个月之后，记忆库从几百条涨到几万条，检索变慢。处理办法：

1. 开启审计任务，把置信度低于 0.5 且 30 天未被检索的记忆标记为待清理。
2. 对高频检索的记忆做摘要合并，把多条相关记忆压缩成一条。
3. 给向量索引加分区，按时间或类型分表。

第 2 步的摘要合并要谨慎，合并后的记忆置信度取原记忆的最高值，避免把低质量内容“洗白”。

5.4 与 LLM 客户端对接的注意事项

热词里提到 “llm request failed: provider rejected the request schema or tool payload”，这是 MCP 对接时常见的报错。原因通常是工具的参数 schema 和客户端期望的不一致。排查步骤：

• 确认 MCP server 返回的工具定义符合协议版本。
• 检查参数类型，比如top_k必须是整数，传字符串会被拒。
• 看客户端日志里具体是哪个字段不匹配。

我遇到过一次是tags字段定义成字符串，但客户端按数组传，改一下 schema 就好了。

6. 记忆系统的扩展方向与个人体会

hindsight 跑通之后，能扩展的地方不少。比如把记忆和 RAG 结合，检索时先查记忆再查文档，记忆提供上下文，文档提供细节。热词里提到的 “rag graphrag llm wiki 本体rag” 就是这个方向——用本体（ontology）来组织记忆之间的关系，而不只是平铺的条目。

另一个方向是接入更多 MCP 客户端。现在支持 MCP 的工具越来越多，浏览器扩展、IDE、命令行工具都能接。你可以在 Chrome 扩展设置里启用 MCP 连接，让浏览网页时的助手直接读写 hindsight 的记忆，把“看到的有用信息”随手存进去。

我个人在实际操作中的体会是：记忆系统的价值不在于存了多少，而在于取出来的那几条是不是真的有用。与其追求大而全，不如先把写入质量管好，置信度、标签、查重这三件事做到位，检索效果自然就上来了。我见过太多项目死在“什么都往里塞”，最后检索出来一堆噪声，模型反而被带偏。

最后分享一个小技巧：定期用真实查询做一轮人工评测，每次抽 20 条查询，看前 3 条结果里有没有真正相关的。这个习惯坚持下来，你会对系统的实际表现有清醒的认识，而不是被“记忆库有十万条”这种数字迷惑。