Agent Memory 分层架构与 MCP 实战：从记忆写入到 Docker 部署

1. 从“hindsight”说起：为什么记忆是 Agent 落地的最后一公里

“hindsight”这个词本身很有意思，字面意思是“事后的洞察力”，也就是我们常说的“后见之明”。把这个词放到 Agent Memory 这个语境里，它其实精准地戳中了一个痛点：一个 LLM Agent 在跑完一轮任务之后，能不能回过头来，把刚才发生的事、做过的决策、踩过的坑，变成下一次可以直接调用的经验。这件事听起来简单，做起来极难，因为它牵扯到记忆的写入、存储、检索、衰减、冲突消解这一整套链路。

我接触过不少做 Agent 的团队，模型选的是顶配，工具链也搭得很全，MCP 协议接了一堆，Docker 环境跑得飞起，但一到多轮任务就露馅——Agent 像个失忆症患者，上一轮告诉它“用户偏好用中文回复”，下一轮它又开始飙英文；上一轮已经确认过某个 API 的鉴权方式，下一轮它又重新试错一遍。这不是模型能力问题，是记忆架构没设计好。hindsight 这个项目标题，本质上就是在问一个问题：Agent 的记忆，到底该怎么存、怎么取、怎么用，才能让它在时间维度上真正“长记性”。

这篇文章适合三类人看。第一类是正在做 Agent 应用开发、被多轮上下文折磨过的工程师；第二类是对 MCP 协议、Docker 部署、LLM 记忆机制感兴趣、想动手搭一套可复现方案的技术爱好者；第三类是产品侧的同学，想搞清楚 Agent Memory 到底能带来什么体验差异。我会从架构设计讲到实操部署，从记忆分层讲到检索策略，尽量把每个“为什么这么设计”讲透，而不是只丢一堆配置让你抄。

需要提前说明的是，Agent Memory 这个领域目前没有银弹，hindsight 也不是某个现成的开源项目名，它更像是一类设计思路的代称——让 Agent 具备“回看过去、提炼经验”的能力。我下面讲的内容，是基于当前主流实践（向量检索、结构化记忆、MCP 工具调用、Docker 容器化部署）做的一套可落地组合方案，你可以把它当成一个参考架构，按自己的业务裁剪。

2. 记忆分层设计：别把所有东西都塞进向量库

2.1 为什么“一个向量库走天下”是错的

很多人一提 Agent Memory，第一反应就是“上向量数据库，把对话历史 embedding 一下存进去，检索的时候做相似度匹配”。这个方案在 Demo 阶段能跑通，但一上生产就崩。原因有三个。

第一，语义相似不等于任务相关。用户上一轮说“帮我查一下北京明天的天气”，这一轮说“那上海呢”，两句话 embedding 相似度很高，但如果你只靠向量检索，很可能把三天前另一段关于“北京天气”的旧对话也捞出来，而那段对话的上下文（比如当时用户问的是穿衣建议）和当前任务（对比城市天气）完全不搭。向量检索擅长找“像”的，不擅长找“对”的。

第二，记忆有生命周期。有些记忆是永久的（用户身份、偏好设置），有些是会话级的（当前任务的中间状态），有些是临时的（刚刚调用工具返回的结果）。全塞一个库里，检索时没有优先级，噪音会淹没信号。

第三，结构化信息会被 embedding 稀释。比如“用户 ID 是 10086，VIP 等级 3，上次投诉时间是 3 月 12 日”这种信息，embedding 之后变成一串浮点数，检索出来还得靠 LLM 再解析一遍，既浪费 token 又容易出错。这类信息应该用结构化存储，直接 key-value 查。

所以 hindsight 思路下的记忆架构，核心是分层。我一般把它分成四层：工作记忆、情景记忆、语义记忆、程序记忆。下面逐层拆。

2.2 四层记忆的职责划分与存储选型

工作记忆（Working Memory）是当前会话的“草稿纸”，存的是这一轮任务正在用的上下文：用户刚说的话、Agent 刚调用的工具返回、中间推理步骤。它的特点是读写极频繁、生命周期短（会话结束或任务完成就清）。存储上我推荐直接用内存 + Redis，不要碰向量库。Redis 的 List 或 Hash 结构足够，读写延迟在毫秒级，而且支持 TTL 自动过期，省得你手动清理。

情景记忆（Episodic Memory）是“发生过什么”的记录，比如“3 月 12 日用户投诉了物流延迟，Agent 给出了补偿方案，用户接受了”。这类记忆需要按时间线检索，也需要按语义检索。我的做法是双写：一份结构化记录进 PostgreSQL（带时间戳、事件类型、参与方），一份摘要 embedding 进向量库（用于语义召回）。检索时先用结构化条件过滤时间范围，再用向量做二次排序。

语义记忆（Semantic Memory）是“我知道什么”的事实性知识，比如“用户偏好中文回复”“这个 API 的 rate limit 是 100 QPS”。这类记忆更新频率低、读取频率高，适合用结构化存储 + 缓存。我通常用 PostgreSQL 存主数据，Redis 做热点缓存，向量库只存那些需要模糊匹配的（比如“用户提到过喜欢某个品牌”这种非精确事实）。

程序记忆（Procedural Memory）是“怎么做”的技能，比如“调用退款接口前必须先查订单状态”。这类记忆最容易被忽略，但对 Agent 稳定性影响最大。它适合用规则引擎或工作流引擎来存，比如用 JSON 描述前置条件、执行步骤、后置校验，Agent 在执行任务前先查一遍程序记忆，避免重复踩坑。

这个分层不是拍脑袋定的，它对应的是认知科学里对人类记忆的经典划分。你不需要严格照搬，但“按用途分存储”这个原则一定要守住。我见过太多项目把用户偏好和临时工具返回混在一个向量库里，结果检索时要么召回一堆无关的，要么把重要偏好淹没了。

2.3 记忆写入的时机与去重策略

分层定好了，下一个问题是：什么时候写？我的经验是三个触发点。

第一个触发点是任务完成时。一轮任务跑完，把关键决策、结果、用户反馈提炼成一条情景记忆。注意是“提炼”不是“全存”，原始对话太长了，直接存进去既占空间又降检索质量。提炼可以用 LLM 做摘要，prompt 大概是“请用一句话总结这次任务的目标、采取的行动、最终结果，以及任何值得下次注意的点”。

第二个触发点是用户显式纠正时。用户说“不对，应该是这样”，这属于高价值信号，必须立刻写入语义记忆或程序记忆。这类记忆的权重应该设高，检索时优先返回。

第三个触发点是工具调用失败时。失败经验比成功经验更值得记，因为它能防止 Agent 重复踩坑。我一般会把失败原因、错误码、当时的参数一起存进程序记忆，下次遇到类似场景先查一遍。

去重是个容易被忽视的坑。同一个事实被反复写入，向量库里会出现大量近似重复的记录，检索时浪费 token 还降低精度。我的做法是写入前先做一次相似度检查，如果已有记录的相似度超过阈值（比如 0.92），就更新旧记录的权重和时间戳，而不是新增一条。这个逻辑可以用向量库的 upsert 配合 metadata 过滤来实现。

3. MCP 协议在记忆系统里的角色：别把它只当工具调用

3.1 MCP 的本质是“能力协商层”

MCP（Model Context Protocol）这两年被讨论得很多，但很多人对它的理解停留在“让 LLM 调用外部工具”这个层面。这个理解不算错，但太窄了。MCP 真正的价值在于它定义了一套标准化的能力协商机制：Agent 不需要提前知道有哪些工具可用，它可以通过 MCP 动态发现、动态调用、动态获取上下文。

放到记忆系统里，MCP 可以承担三个角色。第一个角色是记忆读写接口。你可以把记忆库封装成一个 MCP Server，暴露memory_write、memory_search、memory_update这几个工具，Agent 通过 MCP 协议来操作记忆，而不是硬编码在业务逻辑里。这样做的好处是记忆层和 Agent 层解耦，换存储后端不用改 Agent 代码。

第二个角色是上下文注入。MCP 支持 resource 概念，你可以把用户画像、历史摘要这些内容注册成 resource，Agent 在启动时自动拉取，作为 system prompt 的一部分。这比每次手动拼 prompt 优雅得多。

第三个角色是跨 Agent 记忆共享。如果你有多个 Agent 协作，比如一个负责客服、一个负责售后，它们可以通过同一个 MCP Server 共享记忆，避免各自为政。这个场景在复杂业务里很常见，MCP 的标准化协议让这件事变得可行。

3.2 用 MCP 封装记忆服务的实操结构

我拿一个具体例子来说明怎么搭。假设你要做一个客服 Agent 的记忆服务，用 MCP 封装，目录结构大概是这样：

memory-mcp-server/ ├── src/ │ ├── index.ts # MCP Server 入口 │ ├── tools/ │ │ ├── write.ts # memory_write 工具 │ │ ├── search.ts # memory_search 工具 │ │ └── update.ts # memory_update 工具 │ ├── resources/ │ │ └── profile.ts # 用户画像 resource │ └── storage/ │ ├── redis.ts # 工作记忆 │ ├── postgres.ts # 结构化记忆 │ └── vector.ts # 向量记忆 ├── Dockerfile └── docker-compose.yml

memory_write工具的入参设计很关键，我一般要求传这几个字段：content（记忆内容）、type（episodic / semantic / procedural）、importance（1-5 权重）、ttl（可选，过期时间）、metadata（结构化标签）。出参返回写入后的记忆 ID 和去重结果。

memory_search的入参包括query（查询文本）、type（可选，限定记忆类型）、top_k（返回条数）、time_range（可选，时间过滤）。内部实现是先按 type 和 time_range 做结构化过滤，再对候选集做向量召回，最后用 importance 和时间衰减做重排序。

这里有个细节值得说：时间衰减函数。一条三个月前的记忆和一条昨天的记忆，即使语义相似度一样，权重也应该不同。我用的公式是score = similarity * importance * exp(-λ * days_ago)，λ 取 0.01 左右，意味着大约 70 天后权重衰减到一半。这个参数可以根据业务调，客服场景可以衰减快一点，知识库场景可以慢一点。

3.3 MCP 工具调用的错误处理与重试

MCP 调用不是百分百可靠的，网络抖动、服务重启、参数错误都会导致失败。我在实操里总结了几个必须处理的场景。

第一个场景是工具不存在。Agent 可能调用了一个没注册的工具名，这时候 MCP Server 应该返回明确的错误码，而不是静默失败。Agent 侧要能捕获这个错误，并决定是换工具还是放弃。

第二个场景是参数校验失败。比如memory_write的type传了一个不存在的值，Server 应该返回 400 级别的错误，并附带合法值列表。Agent 拿到错误后可以自动修正重试。

第三个场景是超时。记忆检索如果超过 2 秒还没返回，Agent 不应该干等，应该走降级逻辑——比如只返回工作记忆，跳过长期记忆检索。这个降级策略要提前设计好，不能等线上出问题再补。

重试策略我一般设成最多 2 次，间隔用指数退避（200ms、500ms）。超过 2 次就放弃，记录日志，让 Agent 走无记忆路径。记住，记忆是增强，不是依赖，记忆服务挂了 Agent 也得能跑。

4. Docker 化部署：把记忆服务跑成可复现的环境

4.1 为什么记忆服务一定要容器化

我强烈建议把记忆服务容器化，原因有三个。第一，依赖复杂。一个完整的记忆服务要跑 Redis、PostgreSQL、向量库（比如 Qdrant 或 Milvus）、MCP Server，手动装环境能折腾一整天，还容易版本冲突。第二，环境一致性。开发机跑通了，测试环境跑不通，这种事太常见了，容器化能把这个变量消掉。第三，弹性伸缩。记忆检索是 IO 密集型，流量上来的时候需要快速扩容，容器编排比手动部署快得多。

Docker Desktop 在 Windows 和 macOS 上都能用，Linux 上直接装 Docker Engine 就行。这里有个坑要提醒：Windows 上装 Docker Desktop 需要开启 WSL2 或者 Hyper-V，如果 BIOS 里虚拟化没开，会报 “Virtualization support not detected” 的错误。解决办法是进 BIOS 把 Intel VT-x 或 AMD-V 打开，然后在 Windows 功能里启用“虚拟机平台”和“适用于 Linux 的 Windows 子系统”。

4.2 docker-compose 编排记忆服务全栈

下面是我常用的一套 docker-compose 配置，把记忆服务需要的组件都编排进去。你可以直接拿去改。

version: "3.9" services: redis: image: redis:7-alpine ports: - "6379:6379" volumes: - redis_data:/data command: redis-server --appendonly yes healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 3s retries: 3 postgres: image: postgres:16-alpine ports: - "5432:5432" environment: POSTGRES_USER: memory POSTGRES_PASSWORD: memory_pass POSTGRES_DB: agent_memory volumes: - pg_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U memory"] interval: 10s timeout: 3s retries: 3 qdrant: image: qdrant/qdrant:latest ports: - "6333:6333" - "6334:6334" volumes: - qdrant_data:/qdrant/storage healthcheck: test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"] interval: 10s timeout: 3s retries: 3 memory-mcp: build: ./memory-mcp-server ports: - "8080:8080" environment: REDIS_URL: redis://redis:6379 POSTGRES_URL: postgresql://memory:memory_pass@postgres:5432/agent_memory QDRANT_URL: http://qdrant:6333 DECAY_LAMBDA: "0.01" TOP_K: "5" depends_on: redis: condition: service_healthy postgres: condition: service_healthy qdrant: condition: service_healthy volumes: redis_data: pg_data: qdrant_data:

这份配置里有几个设计点值得解释。healthcheck是必须的，因为depends_on默认只等容器启动，不等服务就绪，没有 healthcheck 的话 memory-mcp 可能在数据库还没初始化完就启动，直接报连接错误。volumes保证数据持久化，容器重启不丢记忆。DECAY_LAMBDA和TOP_K做成环境变量，方便不同环境调参。

启动命令就一行：

docker compose up -d

第一次跑会拉镜像、建表、初始化向量库 collection，大概需要两三分钟。跑起来之后用docker compose ps检查所有服务是不是 healthy 状态。

4.3 向量库 collection 的初始化与索引参数

Qdrant 的 collection 需要手动创建，并且要指定向量维度和距离度量。维度取决于你用的 embedding 模型，比如 OpenAI 的 text-embedding-3-small 是 1536 维，BGE-M3 是 1024 维。距离度量一般用 Cosine，因为文本 embedding 通常做了归一化。

from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams client = QdrantClient(url="http://localhost:6333") client.create_collection( collection_name="agent_memory", vectors_config=VectorParams( size=1024, distance=Distance.COSINE ), hnsw_config={ "m": 16, "ef_construct": 100 } )

m和ef_construct是 HNSW 索引的参数。m控制每个节点的连接数，越大召回率越高但内存占用越大，16 是个平衡点。ef_construct控制建索引时的搜索深度，100 是常用值。这两个参数在数据量小于 100 万时基本不用调，超过之后再考虑优化。

还有一个容易踩的坑：payload 索引。如果你经常按type或user_id过滤，一定要给这些字段建 payload 索引，否则 Qdrant 会做全量扫描，性能差一个数量级。

client.create_payload_index( collection_name="agent_memory", field_name="type", field_schema="keyword" ) client.create_payload_index( collection_name="agent_memory", field_name="user_id", field_schema="keyword" )

5. 记忆检索的实战调优：从“能查到”到“查得准”

5.1 混合检索：向量 + 关键词 + 结构化过滤

纯向量检索的召回率在真实业务里往往不够看，尤其是当查询里包含专有名词、订单号、产品型号这类信息时，embedding 会把这些细节抹平。我的做法是混合检索：先用结构化条件做粗筛，再用关键词做精确匹配，最后用向量做语义补充，三路结果合并后重排序。

具体流程是这样：用户查询进来，先解析出结构化条件（比如 user_id、时间范围、记忆类型），用这些条件从 PostgreSQL 里捞一批候选；同时对查询做关键词提取，用 BM25 或 PostgreSQL 的全文检索捞一批；再把查询 embedding 一下，从 Qdrant 里召回一批。三批结果用 RRF（Reciprocal Rank Fusion）算法合并，公式是score = Σ 1/(k + rank_i)，k 一般取 60。

RRF 的好处是不需要归一化不同来源的分数，直接按排名融合，简单又稳。我实测下来，混合检索比纯向量检索的召回率能提升 20% 到 30%，尤其是在长尾查询上。

5.2 重排序：让最相关的记忆排在最前面

召回之后是重排序。这一步可以用 Cross-Encoder 模型，比如 BGE-Reranker，它对 query 和 document 做联合编码，精度比双塔模型高不少。代价是慢，所以只对 Top 20 的候选做重排，选出 Top 5 返回给 Agent。

重排序的输入是(query, memory_content)对，输出是相关性分数。我一般会把 importance 和时间衰减也乘进去，最终分数是rerank_score * importance * decay。这样既考虑了语义相关性，又考虑了记忆本身的价值和新鲜度。

有个细节要注意：重排序模型和 embedding 模型最好用同一家的，比如都用 BGE 系列，这样语义空间一致，效果更稳。混用不同家的模型有时候会出现分数分布不匹配的问题。

5.3 检索结果注入 Prompt 的格式设计

检索出来的记忆怎么塞进 prompt，这件事直接影响 Agent 的使用效果。我见过有人直接把记忆列表拼成一段文本丢进去，结果 Agent 要么忽略，要么误用。我的做法是结构化注入，给每条记忆标注类型、时间、置信度，让 Agent 知道该怎么用。

[记忆上下文] 以下是与当前任务相关的历史记忆，按相关性排序： 1. [语义记忆 | 置信度 0.95 | 2024-03-10] 用户偏好中文回复，不喜欢冗长的解释。 2. [程序记忆 | 置信度 0.88 | 2024-03-08] 调用退款接口前必须先查询订单状态，否则会报 400 错误。 3. [情景记忆 | 置信度 0.72 | 2024-03-05] 用户曾投诉物流延迟，当时给出的补偿方案是优惠券，用户接受。 请结合以上记忆处理当前任务，如记忆与当前情况冲突，以当前情况为准。

最后那句“如记忆与当前情况冲突，以当前情况为准”很重要，它给 Agent 一个优先级判断依据，避免被过期记忆带偏。置信度字段也让 Agent 知道哪些记忆更可信。

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

6.1 记忆检索返回空结果怎么办

这是最常见的问题，排查思路按顺序来。先确认向量库 collection 里到底有没有数据，用count接口查一下。如果数据量为 0，说明写入环节有问题，检查 MCP Server 的日志看memory_write有没有报错。如果数据量正常但检索为空，检查 embedding 模型是不是和写入时用的同一个，维度不匹配会直接报错，但有些客户端会静默返回空。

还有一个隐蔽的原因：过滤条件太严。比如你同时限定了type=semantic和time_range=最近 7 天，但语义记忆可能三个月才更新一次，自然查不到。这时候应该放宽条件，或者做多路检索，某一路为空不影响其他路。

6.2 记忆写入重复导致检索噪音大

前面提过去重，这里补充一个实操技巧：用内容哈希做精确去重，用向量相似度做模糊去重。内容哈希很简单，对记忆文本做 MD5，写入前查一下哈希是否存在。模糊去重就是算余弦相似度，超过阈值就更新而不是新增。

阈值怎么定？我的经验是 0.92 到 0.95 之间。太低会误合并不同记忆，太高去重效果不明显。这个值可以用一批标注数据调出来，没有标注数据的话就先用 0.93，观察一段时间再调。

6.3 Docker 容器间网络不通的排查

容器间网络不通，九成是服务名写错了或者端口没对上。docker-compose 里服务之间用服务名做 hostname，比如 memory-mcp 连 Redis 应该用redis://redis:6379，而不是localhost:6379。localhost 在容器里指向容器自己，不是宿主机。

如果服务名没错还是不通，用docker compose exec memory-mcp ping redis测一下连通性。ping 不通说明网络层有问题，检查是不是在不同的 network 里。docker-compose 默认会创建一个共享 network，所有服务都在里面，一般不会有问题，除非你手动指定了 network。

还有一个坑是启动顺序。虽然配了depends_on和 healthcheck，但如果你的应用启动时只连一次数据库，连不上就退出，那还是会有问题。解决办法是在应用侧加重试逻辑，启动时连不上就等几秒重试，最多重试 10 次。

6.4 记忆膨胀导致成本失控

跑一段时间后，向量库越来越大，检索越来越慢，token 消耗越来越高。这是记忆系统必须面对的熵增问题。我的应对策略是分级衰减 + 定期归档。

分级衰减是指不同重要性的记忆有不同的保留策略。importance 为 5 的记忆永久保留，4 的保留一年，3 的保留半年，2 的保留一个月，1 的保留一周。这个策略用定时任务实现，每天扫一遍，过期的删掉或归档到冷存储。

定期归档是指把超过一定时间的记忆从向量库移到对象存储，需要的时候再捞回来。这样向量库始终保持在一个可控的规模，检索性能不会随时间退化。

7. 我在实操中踩过的几个坑

第一个坑是embedding 模型换版本。有一次我把 embedding 模型从 v1 升到 v2，忘了重新 embedding 历史数据，结果新旧向量混在一个 collection 里，检索结果乱七八糟。教训是：换模型必须重建 collection，或者用双 collection 做灰度迁移。

第二个坑是MCP Server 无状态设计。我一开始把会话状态存在 MCP Server 的内存里，结果一重启就丢。后来改成所有状态都落 Redis，Server 本身无状态，随便重启扩容都不影响。

第三个坑是过度依赖记忆。有段时间 Agent 什么都查记忆，连“今天星期几”都要检索一遍，延迟高得离谱。后来我加了个规则：只有涉及用户偏好、历史事件、操作规范的问题才查记忆，通用知识直接走模型本身。这个边界要划清楚，不然记忆系统会变成性能瓶颈。

第四个坑是忽略记忆的隐私属性。有些记忆包含用户敏感信息，不能明文存。我的做法是敏感字段加密存储，检索时只返回脱敏后的摘要，需要详情时再走鉴权解密。这个在合规要求高的场景里是必须的。

8. 后续可以怎么扩展

如果你已经把基础版跑通了，可以考虑几个扩展方向。一是记忆的主动遗忘，让 Agent 自己判断哪些记忆不再需要，主动删除，而不是等 TTL 过期。二是跨用户记忆迁移，比如同一个团队的用户可以共享某些程序记忆，提升整体效率。三是记忆的可解释性，当 Agent 做出某个决策时，能回溯到是哪条记忆影响了它，这对调试和审计很有价值。

我个人在实际操作中的体会是，Agent Memory 这件事，架构设计占七成，调优占三成。分层分对了，后面就是参数问题；分层分错了，怎么调都是打补丁。hindsight 这个词提醒我们，记忆的价值不在于存了多少，而在于能不能在正确的时刻，把正确的经验，送到正确的地方。