Agent Memory 实战：从分层设计到 MCP 与 Docker 落地

1. 从"hindsight"这个词说起：为什么记忆是Agent最被低估的能力

第一次看到"hindsight"这个项目名，我脑子里蹦出来的不是技术架构，而是一个很朴素的场景：你跟一个助手聊了半小时，把项目的来龙去脉、几个关键决策、踩过的坑都讲清楚了，结果第二天再问它，它一脸茫然，仿佛昨天那半小时从没发生过。这不是模型不够聪明，而是它压根没有"记忆"这个能力层。

hindsight 这个词本身是"事后之明""后见之明"的意思。放在 Agent 语境里，它指向一个非常具体的问题：Agent 如何把过去发生过的事情，变成当下决策的依据。这跟传统的"上下文窗口"完全是两码事。上下文窗口是临时的、易失的、有长度上限的；而记忆是持久的、可检索的、可累积的。很多人做 Agent 做到一定阶段都会撞上这堵墙——模型能力没问题，工具调用也没问题，但就是"记不住事"，导致每次交互都像第一次见面。

这篇内容我想围绕 hindsight 这个方向，把 Agent Memory（智能体记忆）这件事从概念到落地讲透。关键词里出现了 agent memory、LLM、MCP、Docker，还有一堆热词比如 working memory、agent 存储、MCP 协议、Docker 安装等等，说明关注这个方向的人，既有想搞懂原理的，也有想直接跑起来一套可复现环境的。我会兼顾这两类读者：先讲清楚记忆到底分几层、每层解决什么问题，再落到具体的存储选型、MCP 集成、Docker 部署这些能直接抄作业的环节。

适合谁看？如果你正在做基于 LLM 的 Agent 应用，发现对话一长就"失忆"，或者你想给现有的助手加一个跨会话的记忆层，再或者你只是好奇 MCP 和 Agent Memory 到底怎么配合，这篇都能给你一条清晰的路径。我不打算堆概念，而是按"为什么这么设计—怎么落地—踩过哪些坑"的顺序来讲，尽量让你看完就能动手。

先说一个反直觉的结论：大多数 Agent 的"记忆问题"，本质不是存储问题，而是检索和写入策略问题。你就算给它接一个数据库，如果不知道该写什么、什么时候写、怎么召回，那这个数据库就是个摆设。hindsight 这类项目真正有价值的地方，恰恰在于它定义了"记忆的生命周期"，而不只是提供一个存东西的地方。

2. Agent Memory 的分层：working memory、episodic、semantic 到底怎么分

2.1 为什么不能只有"一个记忆库"

很多人一开始的想法很直接：搞一个向量库，把所有对话都塞进去，需要的时候检索一下不就行了？我最早也是这么干的，结果很快就发现问题——检索出来的东西要么太碎（一句无关紧要的寒暄），要么太泛（一段没有上下文的结论），真正有用的信息反而被淹没了。

原因在于，不同性质的记忆，检索方式和使用场景完全不同。学术界和工程界比较通用的分法是把 Agent Memory 分成几层，我结合实操给你翻译一下：

• Working Memory（工作记忆）：当前任务进行中的临时状态。比如"用户正在填一张报销单，已经填到第 3 步"。它生命周期短，任务结束就丢弃，但读写极其频繁。这一层通常直接放在上下文里，或者放在一个快速的 KV 存储里。
• Episodic Memory（情景记忆）：具体发生过的事件。"上周三用户让我帮他改了一段 Python 代码，用的是 pandas"。它带时间戳、带具体情境，检索时往往按时间或相似度召回。
• Semantic Memory（语义记忆）：从多次事件中提炼出的稳定知识。"这个用户偏好函数式写法""这个项目的日志统一用 loguru"。它是抽象的、去情境化的，写入频率低但价值高。

这三层不是互斥的，而是有转化关系的。情景记忆积累多了，可以蒸馏成语义记忆；工作记忆结束后，有价值的部分沉淀成情景记忆。hindsight 这个方向要解决的，就是这套"记忆的流转机制"。

2.2 三层记忆的读写时机对照

我把这三层的读写策略整理成一张表，方便你对照自己的场景：

这张表看着简单，但每一格背后都有坑。比如 Working Memory 的"每轮写入"，如果你无脑把整段对话都塞进去，上下文很快就被撑爆；正确做法是只保留"状态增量"，也就是这一步相比上一步多了什么、变了什么。

再比如 Semantic Memory 的"定期蒸馏"，这个"定期"到底是多久？我的经验是不要用固定时间，而是用事件触发——当某个情景记忆被重复召回超过 N 次，或者用户明确纠正了某个行为，就触发一次蒸馏。这样提炼出来的语义记忆才有价值，而不是一堆没人用的"总结"。

2.3 一个容易被忽略的点：记忆的"遗忘"也是功能

新手做记忆系统，总想着"记得越多越好"。但真实场景里，遗忘和记忆同样重要。一个什么都记得的 Agent，会被大量过时、矛盾、无关的信息干扰，决策质量反而下降。

hindsight 这个命名其实暗含了这层意思——"事后之明"意味着你要能回看、能筛选、能判断哪些过去值得被记住。工程上，遗忘机制通常有三种实现：

1. 时间衰减：越老的记忆权重越低，检索时自然排在后面。
2. 冲突消解：当新记忆和旧记忆矛盾时，标记旧记忆为"已失效"而不是直接删除，保留可追溯性。
3. 容量淘汰：给每层记忆设上限，超了就按"最近最少使用 + 价值评分"淘汰。

我实测下来，冲突消解是最容易被忽略但最关键的。比如用户先说"我用 Windows"，后来说"我换 Mac 了"，如果两条都留着且权重相同，Agent 就会精神分裂。正确做法是给记忆加一个superseded_by字段，检索时自动过滤掉被取代的条目。

3. MCP 在记忆系统里扮演什么角色：协议层解耦的价值

3.1 MCP 不是"记忆本身"，而是"记忆的插座"

热词里 MCP 出现频率极高，很多人会问：MCP 和 Agent Memory 是什么关系？我的理解是——MCP 是让记忆能力可以被标准化接入的协议层，它本身不存记忆，但它定义了"Agent 怎么跟记忆服务对话"。

打个比方：记忆服务像一台冰箱，MCP 像墙上的标准插座。你不需要每次换冰箱都重新布线，只要插头对得上就行。在没有 MCP 之前，每个 Agent 框架接记忆库都要写一套自己的适配代码，换个框架就得重写。有了 MCP，记忆服务只要实现标准的工具接口（比如memory_write、memory_search、memory_forget），任何支持 MCP 的 Agent 都能直接调用。

这对 hindsight 这类项目意义很大：它可以把记忆逻辑封装成一个独立的 MCP Server，Agent 侧只负责调用，两边解耦，各自演进。

3.2 一个记忆 MCP Server 应该暴露哪些工具

基于常见实践，一个可用的记忆 MCP Server 通常会暴露这几类工具，我按重要性排序：

• memory_write：写入一条记忆，参数包括内容、类型（episodic/semantic）、标签、时间戳。
• memory_search：按语义相似度 + 元数据过滤检索，返回带相关度的结果。
• memory_update：更新已有记忆，常用于冲突消解。
• memory_forget：显式删除或标记失效。
• memory_summarize：对一段情景记忆做蒸馏，生成语义记忆。

这里有个设计细节值得说：memory_search的返回结果一定要带"为什么被召回"的信息。比如返回{"content": "...", "score": 0.87, "matched_on": "semantic_similarity", "recency": "3 days ago"}。这样 Agent 在决策时能判断这条记忆可不可信，而不是盲目采信。我见过太多系统只返回一个裸文本，结果 Agent 把三天前的一条临时备注当成了长期偏好。

3.3 MCP 集成的常见坑：工具描述写不好，模型就不会用

MCP 的工具体系依赖模型自己决定"什么时候调哪个工具"。这意味着工具的描述文本（description）质量，直接决定调用准确率。我踩过的坑是：把memory_search的描述写成"搜索记忆"，结果模型经常在该写入的时候去搜索，该搜索的时候不调用。

后来我改成更具体的描述，比如：

当用户提到过去发生过的事情、需要回忆之前的偏好或决策时调用此工具。输入应为自然语言查询，不要传入单字或空字符串。

调用准确率明显提升。这个经验对所有 MCP 工具都适用：描述里要写清楚"什么时候用""什么时候不用""输入格式要求"，模型不是人，它需要显式边界。

另外，MCP 工具的返回内容也要控制长度。如果memory_search一次返回 20 条记忆，每条 500 字，上下文瞬间被占满。我的做法是默认返回 top-3，并且每条截断到 200 字以内，需要详情时再单独调memory_get。

4. 存储选型：向量库、图数据库、关系库到底怎么搭

4.1 没有银弹，只有组合

热词里出现了 tencentdb agent memory、agent 存储这些词，说明大家在纠结"记忆到底存哪"。我的结论很明确：单一存储搞不定三层记忆，必须组合。下面是我实际用过的几种组合方案和适用场景。

方案 A：向量库 + Redis

• 向量库（如 Milvus、Qdrant、pgvector）存 episodic 和 semantic 记忆，负责语义检索。
• Redis 存 working memory，负责高速读写和过期淘汰。
• 适合：中小规模、以语义检索为主的场景。

方案 B：图数据库 + 向量库

• 图数据库（如 Neo4j）存实体之间的关系，比如"用户—偏好—函数式写法"。
• 向量库存原始文本，负责模糊召回。
• 适合：需要多跳推理的场景，比如"用户上次提到的那个同事，他负责的项目是什么"。

方案 C：关系库 + 向量扩展

• 直接用 PostgreSQL + pgvector，一张表搞定元数据 + 向量。
• 适合：想少维护一个组件、数据量不大的团队。

我个人的默认选择是方案 C，因为运维成本最低，而且 pgvector 的性能对大多数 Agent 场景够用了。等数据量真的上来了，再拆成方案 A 或 B。

4.2 向量维度和距离度量的选择

选向量库绕不开两个参数：维度和距离度量。维度取决于你用的 embedding 模型，这个没得选，模型输出多少就是多少。但距离度量有讲究：

• 余弦相似度（cosine）：最常用，对向量长度不敏感，适合文本语义。
• 内积（inner product）：当向量已归一化时等价于余弦，计算更快。
• 欧氏距离（L2）：对绝对位置敏感，文本场景用得少。

我的经验是：文本记忆一律用余弦，别折腾。除非你有特殊需求（比如向量已经归一化且追求极致性能），否则余弦是最稳的默认值。

还有一个坑：不同 embedding 模型的向量不能混存。如果你中途换了模型，旧向量和新向量在同一个空间里没有可比性，检索结果会乱套。正确做法是换模型时全量重算，或者给每条记忆打上embedding_model标签，检索时按模型分组。

4.3 元数据设计：决定检索质量的关键

很多人把注意力全放在向量上，忽略了元数据。但实际检索时，元数据过滤往往比向量相似度更能决定结果好坏。我建议每条记忆至少带这些字段：

• type：episodic / semantic / working
• created_at/updated_at：时间戳
• source：来自哪次会话、哪个任务
• tags：自定义标签，便于分类召回
• importance：重要性评分，用于排序和淘汰
• superseded_by：被哪条记忆取代（冲突消解用）

有了这些字段，检索就能做"语义相似度 + 时间范围 + 类型 + 标签"的复合查询，精度比纯向量高一个档次。比如"召回最近一周内、类型为 semantic、标签含 'coding-style' 的记忆"，这种查询纯向量库根本做不了。

5. 用 Docker 把整套记忆服务跑起来：从零到可用的完整路径

5.1 为什么用 Docker 而不是本地裸装

热词里 Docker 相关的内容一大堆——docker 安装、docker desktop、docker compose、docker 网络不通、windows 安装 docker 等等，说明这是大家落地时最头疼的环节。我的建议很直接：记忆服务涉及多个组件（向量库、缓存、MCP Server），用 Docker Compose 编排是最省心的方式。

裸装的问题在于：版本冲突、依赖污染、换机器要重来一遍。Docker 把这些都封装了，你只需要一份docker-compose.yml，换台机器docker compose up就能复现。对于 hindsight 这种需要长期运行、还要跟 Agent 通信的服务，容器化几乎是必选项。

5.2 一份可用的 docker-compose 骨架

下面这份配置是我实际用过的精简版，包含向量库（Qdrant）、缓存（Redis）和记忆 MCP Server 三个服务。你可以直接拿去改：

version: "3.9" services: qdrant: image: qdrant/qdrant:latest ports: - "6333:6333" - "6334:6334" volumes: - ./data/qdrant:/qdrant/storage restart: unless-stopped redis: image: redis:7-alpine ports: - "6379:6379" command: redis-server --appendonly yes volumes: - ./data/redis:/data restart: unless-stopped memory-mcp: build: ./memory-mcp ports: - "8080:8080" environment: - QDRANT_URL=http://qdrant:6333 - REDIS_URL=redis://redis:6379 - EMBEDDING_MODEL=your-embedding-model depends_on: - qdrant - redis restart: unless-stopped

几个关键点解释一下：

• 端口映射：Qdrant 的 6333 是 HTTP API，6334 是 gRPC。如果你只用 HTTP，6334 可以省掉。
• 数据卷：./data/xxx挂载到容器内，保证容器重启数据不丢。这是新手最容易忘的一步，不挂卷的话docker compose down一执行数据就没了。
• depends_on：保证启动顺序，但注意它只保证"启动顺序"，不保证"服务就绪"。真正的健康检查要用healthcheck。
• restart 策略：unless-stopped让服务在崩溃后自动重启，适合长期运行。

5.3 Windows 上跑 Docker 的常见问题

热词里"windows 安装 docker""virtualization support not detected docker desktop failed to start"这些，我太熟悉了。Windows 上跑 Docker Desktop 最常见的两个坑：

坑一：虚拟化没开。Docker Desktop 依赖 WSL2 或 Hyper-V，而这两个都需要在 BIOS 里开启虚拟化（Intel VT-x / AMD-V）。报错 "virtualization support not detected" 基本都是这个原因。进 BIOS 打开虚拟化，然后在 Windows 功能里启用"虚拟机平台"和"适用于 Linux 的 Windows 子系统"。

坑二：WSL2 没更新。即使虚拟化开了，WSL2 内核太旧也会导致 Docker Desktop 起不来。解决办法是命令行跑wsl --update，然后wsl --shutdown重启一下。

还有一个隐蔽的坑：Docker 网络不通。容器之间用服务名互相访问（比如上面配置里的http://qdrant:6333），这是 Docker Compose 自动创建的内部网络。但如果你在宿主机上用localhost:6333访问，那是另一条路径。搞混这两个，就会出现"容器里能通、宿主机不通"或者反过来。记住：容器内用服务名，宿主机用 localhost + 映射端口。

5.4 启动后的验证步骤

服务起来之后，别急着接 Agent，先做三步验证：

1. Qdrant 健康检查：浏览器打开http://localhost:6333/dashboard，能看到管理界面就说明向量库正常。
2. Redis 连通性：docker exec -it <redis容器名> redis-cli ping，返回PONG就对了。
3. MCP Server 接口：curl http://localhost:8080/health，看返回状态。

这三步都过了，再往下接 Agent。我见过太多人跳过验证直接接，结果出问题时分不清是记忆服务的问题还是 Agent 的问题，排查成本翻倍。

6. 记忆写入与召回的实战策略：让 Agent 真的"记得住、想得起"

6.1 写入策略：不是所有对话都值得记

前面说过，无脑全存是灾难。那到底该存什么？我的判断标准是三条：

• 有状态变化：用户表达了偏好、做了决策、纠正了之前的说法。
• 有可复用信息：项目配置、命名规范、常用工具链。
• 有明确指代：出现了具体的实体（人名、项目名、文件路径）。

反过来，寒暄、重复确认、临时性的中间结果，都不该进长期记忆。实现上，可以在写入前加一个轻量的"记忆价值判断"步骤——用一个小的 LLM 调用或者规则引擎，给每条候选记忆打分，超过阈值才写入。

这里有个技巧：写入时让模型自己生成"记忆摘要"而不是存原文。原文往往冗长且含噪声，摘要更精炼、检索时更准。比如把"用户说他之前用 Java 写后端，但是最近在学 Python，觉得 Python 的语法更简洁，打算以后新项目都用 Python"压缩成"用户偏好：新项目倾向使用 Python"。

6.2 召回策略：多路召回 + 重排序

单一向量检索的召回率有限，我的做法是多路召回再重排序：

1. 语义召回：向量相似度 top-K。
2. 关键词召回：BM25 或全文索引，补充向量漏掉的精确匹配。
3. 时间召回：最近 N 条记忆，保证时效性。
4. 标签召回：按当前任务标签过滤。

四路结果合并后，用一个重排序模型（或者简单的加权打分）排序，取 top-3 注入上下文。这套组合拳下来，召回质量比纯向量高很多，尤其是当用户查询包含具体实体名时，关键词召回能补上向量的短板。

6.3 上下文注入的格式：别让模型"看不懂"记忆

召回出来的记忆怎么塞进 prompt，也有讲究。我试过几种格式，最后稳定用的是这种结构化写法：

[相关记忆] 1. (2024-05-10, 偏好) 用户新项目倾向使用 Python 2. (2024-05-08, 事实) 用户当前项目使用 PostgreSQL + pgvector 3. (2024-05-01, 决策) 用户决定日志统一用 loguru

每条带时间、类型、内容，模型一眼就能判断哪条更相关、哪条可能过时。相比之下，把记忆拼成一大段自然语言，模型反而容易混淆主次。

还有一个细节：记忆注入的位置。放在 system prompt 里还是 user message 里？我的经验是放在 system prompt 的末尾，紧挨着当前任务描述。这样模型在生成回复时，记忆的"新鲜度"最高，被采信的概率更大。

6.4 一个完整的写入-召回闭环示例

把上面的策略串起来，一个典型的闭环是这样的：

1. 用户说："以后这个项目的日志都用 loguru 吧。"
2. 价值判断：有偏好表达，值得记。
3. 生成摘要："用户偏好：项目日志使用 loguru。"
4. 写入 episodic 记忆，打标签coding-style、logging。
5. 若干轮对话后，用户说："帮我加个日志。"
6. 召回：语义 + 标签双路，命中上面那条记忆。
7. 注入上下文，模型生成使用 loguru 的代码。

这个闭环跑通之后，Agent 就真的"记得住"了。而 hindsight 这类项目的价值，就是把这套闭环标准化、可复用，让你不用每个项目都重造一遍。

7. 踩坑实录：记忆系统上线后最容易翻车的几个地方

7.1 记忆污染：错误信息被反复强化

最严重的坑是记忆污染。如果某次 Agent 理解错了用户意图，把错误信息写进了记忆，之后每次召回都会强化这个错误，形成恶性循环。我遇到过一次：用户说"不要用 ORM"，Agent 理解成"不要用 MySQL"，结果后面所有数据库相关的建议都跑偏了。

解决办法有两个：一是写入前做二次确认，对高重要性的记忆（比如偏好、决策）让用户确认；二是提供记忆审计界面，让用户能看到、能纠正、能删除。记忆系统一定要有"人工兜底"的出口，不能全自动。

7.2 检索延迟拖垮体验

向量检索本身不慢，但如果你的记忆库有几十万条，又没有建好索引，单次检索可能几百毫秒甚至上秒。Agent 每轮对话都要召回，累积起来体验就很差。

优化手段：给向量库建 HNSW 索引（Qdrant、Milvus 都支持），把检索从线性扫描降到近似最近邻；缓存高频查询，相同或相似的查询直接返回缓存结果；限制召回数量，top-3 通常够用，别贪多。

7.3 多用户场景下的记忆隔离

单用户场景下记忆系统很简单，一旦多用户就会出问题：A 用户的记忆被 B 用户召回，这是灾难性的。隔离方案有两种：

• 物理隔离：每个用户一个 collection，彻底隔离但资源开销大。
• 逻辑隔离：所有记忆存一起，用user_id字段过滤，检索时强制带上。

我推荐逻辑隔离 + 强制过滤，但要注意过滤条件必须在向量检索之前生效，而不是检索完再过滤。否则既浪费算力，又可能因为 top-K 被其他用户占满而召回不到自己的记忆。Qdrant 支持 payload filter，可以在检索时直接带上user_id条件，这是正确做法。

7.4 记忆和上下文的边界模糊

最后一个坑比较隐蔽：分不清什么该进记忆、什么该留在上下文。我的原则是——当前任务相关的放上下文，跨任务复用的放记忆。比如用户正在填的这张表单，属于上下文；用户填表单时表现出的"喜欢简洁界面"的偏好，属于记忆。

搞混这两者，要么上下文被撑爆，要么记忆里塞满一次性信息。判断标准很简单：这条信息在下一个不相关的任务里还有用吗？有用就进记忆，没用就留在上下文。

8. 关于 hindsight 这类方向，我个人的几点判断

做了一段时间 Agent Memory，我越来越觉得这个方向的核心竞争力不在"存"，而在"判断"——判断什么值得记、什么时候该忘、召回时怎么排序。存储层是基础设施，谁都能搭；但记忆的价值判断逻辑，才是真正拉开差距的地方。

hindsight 这个命名我很喜欢，因为它点出了记忆的本质：不是简单地"记住过去"，而是"用过去的经验指导当下"。一个只会存储的 Agent 是个硬盘，一个能 hindsight 的 Agent 才像个有经验的伙伴。

如果你现在要动手，我的建议是从最小闭环开始：先用 PostgreSQL + pgvector 搭一个单表记忆库，实现最基础的写入和语义召回，跑通之后再逐步加分层、加 MCP、加多路召回。别一上来就追求架构完整，记忆系统的复杂度应该跟着你的实际需求长，而不是跟着论文长。

最后分享一个我一直在用的小技巧：给记忆加一个"最后验证时间"字段。每次某条记忆被召回并成功指导了决策，就更新这个时间。时间越近的记忆，说明越"活跃"，检索时可以给更高权重。这个简单的机制，能让你的记忆系统自动淘汰掉那些长期没被用到的"僵尸记忆"，比单纯按创建时间淘汰聪明得多。