Agent Memory 记忆系统实战：从 LLM 到 MCP 与 Docker 部署

1. 从 "hindsight" 这个名字说起：为什么 Agent Memory 值得单独做一个项目

第一次看到 "hindsight" 这个词，我脑子里蹦出来的不是词典释义，而是那种"事后复盘"的直觉——事情已经发生了，回头看，才发现当时哪一步走对了、哪一步埋了雷。把这个词放到 LLM Agent 的语境里，它指向的东西其实非常具体：Agent 的记忆系统。

现在做 Agent 的人越来越多，大家一开始都盯着模型能力、工具调用、MCP 协议这些"显性"的东西，但真正把 Agent 跑进生产环境之后，你会发现一个很尴尬的现实——Agent 没有记忆，或者说它的记忆是碎的、临时的、用完就丢的。你昨天跟它聊过的偏好，今天它完全不记得；你上周让它处理过的一类任务，这周它还是从零开始摸索。这不是模型不行，是记忆层没搭好。

hindsight 这个项目，我理解它的核心定位就是给 Agent 补上"可回溯、可检索、可复用"的记忆能力。它不是一个简单的对话历史缓存，而是一套完整的记忆管理方案：把 Agent 在运行过程中产生的关键信息——用户偏好、任务上下文、工具调用结果、决策依据——结构化地存下来，并且在需要的时候能够精准地捞回来。

这件事为什么值得单独做一个项目？因为记忆是 Agent 从"玩具"走向"工具"的分水岭。一个没有记忆的 Agent，每次交互都是冷启动，用户得反复交代背景；一个有记忆的 Agent，才能积累、才能进化、才能真正嵌入到工作流里。hindsight 要解决的，就是这个从"无状态"到"有状态"的跨越。

这篇文章我会围绕 hindsight 这个项目，把 Agent Memory 的设计思路、核心机制、实操部署、常见坑点全部拆开讲一遍。涉及到的技术栈包括 LLM、MCP 协议、Docker 部署，以及记忆存储的选型逻辑。不管你是刚接触 Agent 开发的新手，还是已经在跑生产环境的老手，应该都能从里面捞到一些能直接用的东西。

2. Agent Memory 到底难在哪：拆解记忆系统的核心设计思路

2.1 为什么"把对话历史塞进上下文"根本不够用

很多人对 Agent Memory 的第一反应是：不就是把之前的对话记录拼到 prompt 里吗？这个做法在早期确实能凑合，但它有三个致命问题。

第一是上下文窗口的硬限制。不管模型支持 32K、128K 还是更长的上下文，它终究是有限的。你把所有历史都塞进去，很快就会撑爆，而且成本会随着 token 数量线性甚至超线性增长。更关键的是，长上下文并不等于好记忆——模型在超长上下文里的注意力是会被稀释的，关键信息淹没在大量无关内容里，检索精度反而下降。

第二是信息没有结构。原始对话历史是一堆非结构化的文本，里面混杂着闲聊、确认、纠错、真正的决策信息。你直接塞给模型，它得自己从这堆东西里判断哪些重要、哪些可以忽略，这个判断本身就不稳定。

第三是无法跨会话复用。对话历史是绑定在单次会话里的，会话结束，记忆就断了。但真实场景里，用户的需求是跨会话延续的——今天问了一半的问题，明天接着问；这个月形成的偏好，下个月还得生效。

所以 Agent Memory 的核心命题不是"存多少"，而是"存什么、怎么存、怎么取"。这三个问题决定了记忆系统的成败。

2.2 记忆的分层：working memory 与 long-term memory

我在实际项目里会把 Agent 的记忆分成两层来设计，这个分层思路和认知科学里的人类记忆模型是对应的。

Working Memory（工作记忆）是当前任务执行期间的临时记忆。它容量小、生命周期短、访问速度快。比如 Agent 正在处理一个多步骤任务，它需要记住"上一步调用了什么工具、返回了什么结果、当前进行到哪一步"。这部分记忆通常放在内存里，任务结束就可以释放。

Long-term Memory（长期记忆）是跨会话、跨任务持久化的记忆。它容量大、生命周期长、需要检索机制。比如用户的长期偏好、历史任务的解决方案、领域知识沉淀。这部分必须落到持久化存储里，并且要有高效的检索能力。

hindsight 这类项目的价值，很大程度上体现在长期记忆的管理上。因为工作记忆相对好做——就是个临时的状态容器；而长期记忆涉及到存储选型、索引构建、检索策略、更新淘汰一整套工程问题，这才是真正拉开差距的地方。

2.3 记忆的写入策略：不是所有东西都值得记

这里有个很容易被忽略的点：记忆系统的难点不只是"读"，更是"写"。如果什么都往长期记忆里塞，很快就会被垃圾信息淹没，检索质量直线下降。

我在实践中总结的写入判断逻辑大概是这样的：

• 用户显式表达的偏好：必须记。比如"我习惯用 Python 而不是 JavaScript"、"报告要按季度拆分"。
• 任务的关键决策点：值得记。比如"这个方案因为成本原因被否决了"，下次遇到类似场景可以直接复用这个判断。
• 工具调用的稳定结果：选择性记。如果某个 API 的返回格式是固定的，记一次就够了，不用每次都存。
• 闲聊和确认性对话：不记。这些信息没有复用价值，存了只会污染检索结果。

这个"写入过滤"的环节，很多项目做得粗糙，导致记忆库越用越臃肿。hindsight 如果要在记忆质量上做出差异，写入策略的设计是关键。

2.4 检索机制：从关键词匹配到语义检索

记忆存进去之后，怎么在需要的时候精准捞出来？这是另一个核心问题。

最朴素的做法是关键词匹配，但它的召回率很差——用户说"帮我优化一下性能"，记忆里存的是"提升响应速度"，关键词对不上，就检索不到。所以现在主流方案都是向量语义检索：把记忆内容转成 embedding 向量，查询时也转成向量，用余弦相似度找最接近的。

但纯向量检索也有短板，它对精确匹配不敏感。比如你要找"订单号 12345"这种精确信息，向量检索可能给你返回一堆语义相近但订单号不对的结果。所以成熟方案通常是混合检索：向量检索负责语义召回，关键词/BM25 负责精确召回，两路结果融合排序。

hindsight 在检索层如果能把混合检索做扎实，再配合上重排序（rerank），记忆的可用性会有质的提升。

3. 核心技术点逐个拆：LLM、MCP、Docker 在记忆系统里各扮演什么角色

3.1 LLM 在记忆系统里的三重身份

很多人以为 LLM 在记忆系统里只是"被服务方"——记忆是给 LLM 用的。但实际上，LLM 在记忆系统里扮演着三个不同的角色，理解这一点对架构设计很重要。

角色一：记忆的消费者。这是最直观的——检索出来的记忆最终要拼进 prompt，供 LLM 推理使用。这个环节要注意的是记忆的注入方式：是直接拼在 system prompt 里，还是作为工具调用的返回结果？前者简单但不够灵活，后者更符合 Agent 的自主性，但需要模型有较强的工具调用能力。

角色二：记忆的生产者。LLM 需要判断当前对话里哪些信息值得写入长期记忆。这个判断可以做成一个独立的"记忆提取"步骤——让 LLM 对当前对话做一次摘要和结构化，输出"值得记住的要点"。这一步的质量直接决定了记忆库的信噪比。

角色三：记忆的整理者。记忆不是存进去就完事了，还需要定期整理——合并重复项、更新过时信息、建立关联。这些工作也可以交给 LLM 来做，比如让它判断"新记忆和已有记忆是否冲突，是否需要更新"。

这三个角色对应的是记忆系统的读、写、维护三个环节，每个环节对 LLM 的能力要求都不一样。写入环节需要模型有好的信息抽取能力，检索环节需要模型有好的语义理解能力，维护环节需要模型有好的判断和归纳能力。

3.2 MCP 协议：让记忆能力变成可插拔的模块

MCP（Model Context Protocol）这个东西，本质上是给 LLM 和外部能力之间定了一套标准接口。放到 Agent Memory 的场景里，它的价值在于把记忆能力标准化、模块化。

在没有 MCP 之前，你要给 Agent 加记忆，得针对每个框架、每个模型单独适配，代码耦合度很高。有了 MCP，记忆系统可以做成一个独立的 MCP Server，对外暴露几个标准工具：

• memory_write：写入一条记忆
• memory_search：检索相关记忆
• memory_update：更新已有记忆
• memory_delete：删除记忆

Agent 侧只要支持 MCP 协议，就能通过标准方式调用这些能力，不用关心底层记忆是怎么存的、用什么数据库、用什么检索算法。这种解耦对工程维护太重要了——记忆系统的实现可以独立迭代，不影响 Agent 主体。

我在实际项目里踩过的一个坑是：MCP Server 的工具描述（tool description）写得越清晰，模型调用得越准。如果你只写"搜索记忆"，模型可能不知道该传什么参数；如果你写清楚"根据语义相似度检索历史记忆，输入为查询文本，返回最相关的 N 条记忆及其时间戳"，模型的调用成功率会明显提升。这个细节很多人不注意，但它直接影响记忆系统的实际可用性。

3.3 Docker：记忆系统的部署底座

记忆系统涉及多个组件——向量数据库、关系数据库、MCP Server、可能还有 embedding 服务。这些组件如果手动部署，环境依赖能把人折腾疯。Docker 的价值就是把这一整套东西打包成可复现的部署单元。

用 Docker Compose 编排记忆系统，典型的服务划分是这样的：

这里有个实操经验：向量数据库和关系数据库最好分开部署。我见过有人图省事，把向量和元数据都塞进一个库里，结果检索的时候要么性能上不去，要么元数据过滤做不了。分开之后，向量库专注做相似度检索，关系库专注做结构化查询和过滤，各司其职，扩展性也好很多。

Docker 部署还有一个隐性好处：环境一致性。记忆系统对 embedding 模型的版本、向量维度的配置很敏感，一旦环境不一致，检索结果可能完全对不上。用 Docker 把依赖锁死，能避免大量"在我机器上好好的"这类问题。

4. 实操部署：从零把 hindsight 记忆系统跑起来

4.1 环境准备与 Docker 安装要点

先把基础环境搞定。Docker 的安装看起来简单，但有几个坑我必须提前说。

Windows 用户注意虚拟化支持。很多人装 Docker Desktop 会卡在 "virtualization support not detected" 这个报错上。这不是 Docker 的问题，是 BIOS 里的虚拟化开关没打开。你需要进 BIOS，找到 Intel VT-x 或 AMD-V 选项，把它启用。另外 Windows 的 Hyper-V 和 WSL2 也要确认开启，Docker Desktop 现在默认走 WSL2 后端，这个依赖必须满足。

Linux 用户注意权限。装完 Docker 之后，普通用户默认没有权限操作 Docker，每次都要 sudo 很烦。把用户加进 docker 组就行：

sudo usermod -aG docker $USER newgrp docker

执行完记得重新登录一下，让组权限生效。

确认安装成功：

docker --version docker compose version

两个命令都能正常输出版本号，说明环境没问题。如果docker compose报错，可能是装的是老版本的docker-compose（带横杠），注意区分。

4.2 用 Docker Compose 编排记忆系统

下面是我实际用的一套 Compose 配置，做了简化，但核心结构是完整的。你可以直接拿去改。

version: "3.8" services: qdrant: image: qdrant/qdrant:latest ports: - "6333:6333" - "6334:6334" volumes: - ./data/qdrant:/qdrant/storage restart: unless-stopped postgres: image: postgres:16 environment: POSTGRES_USER: memory POSTGRES_PASSWORD: memory_pass POSTGRES_DB: agent_memory ports: - "5432:5432" volumes: - ./data/postgres:/var/lib/postgresql/data restart: unless-stopped memory-mcp: build: ./memory-mcp depends_on: - qdrant - postgres environment: QDRANT_URL: http://qdrant:6333 POSTGRES_DSN: postgresql://memory:memory_pass@postgres:5432/agent_memory EMBEDDING_MODEL: text-embedding-3-small ports: - "8080:8080" restart: unless-stopped

几个关键点解释一下。

端口映射：Qdrant 的 6333 是 HTTP API 端口，6334 是 gRPC 端口。如果你只用 HTTP 接口，6334 可以不映射。Postgres 的 5432 是标准端口，本地开发映射出来方便调试。

数据卷：./data/qdrant和./data/postgres是持久化目录，一定要挂出来。否则容器一删，记忆全没了，这个坑我踩过，血的教训。

依赖顺序：depends_on只保证启动顺序，不保证服务就绪。memory-mcp 启动时 Qdrant 可能还没准备好，所以你的 MCP Server 代码里要有重试逻辑，别一上来就连，连不上就崩。

环境变量：embedding 模型的配置很关键。如果你用外部 API，记得把 key 通过环境变量注入，别硬编码在代码里。

启动命令：

docker compose up -d docker compose logs -f memory-mcp

-d是后台运行，logs -f跟踪日志，方便看启动过程有没有报错。

4.3 记忆写入与检索的核心实现

MCP Server 里最核心的两个工具就是写入和检索。我用 Python 写个简化版示意，重点看逻辑。

写入逻辑：

def memory_write(content: str, metadata: dict): # 1. 生成 embedding vector = embedding_model.encode(content) # 2. 写入向量库 qdrant_client.upsert( collection_name="memories", points=[{ "id": generate_id(), "vector": vector, "payload": { "content": content, "timestamp": now(), **metadata } }] ) # 3. 写入关系库（存结构化字段，方便过滤） db.execute( "INSERT INTO memories (id, content, category, created_at) VALUES (%s, %s, %s, %s)", (memory_id, content, metadata.get("category"), now()) )

这里有个设计决策值得说：为什么向量库和关系库都要写？因为两者服务不同的查询场景。向量库负责"语义相似"的召回，关系库负责"按时间、按类别、按用户"这类结构化过滤。检索时先用关系库缩小范围，再用向量库做语义排序，效率和精度都能兼顾。

检索逻辑：

def memory_search(query: str, top_k: int = 5, filters: dict = None): # 1. 查询向量化 query_vector = embedding_model.encode(query) # 2. 向量检索 results = qdrant_client.search( collection_name="memories", query_vector=query_vector, limit=top_k * 2, # 多召回一些，后面重排 query_filter=build_filter(filters) ) # 3. 重排序（可选但强烈建议） reranked = rerank(query, results)[:top_k] return reranked

多召回再重排这个策略很重要。向量检索的 top_k 直接取 5 条，可能漏掉真正相关的；先召回 10 条，再用更精细的模型重排，取前 5 条，效果会好很多。重排模型可以用 cross-encoder 类的，虽然慢一点，但精度提升明显。

4.4 把记忆能力接入 Agent

MCP Server 跑起来之后，Agent 侧怎么接？以支持 MCP 的客户端为例，配置大概长这样：

{ "mcpServers": { "agent-memory": { "url": "http://localhost:8080/mcp", "transport": "http" } } }

如果你的客户端走 stdio 传输，配置方式会不一样，通常是：

{ "mcpServers": { "agent-memory": { "command": "docker", "args": ["exec", "-i", "memory-mcp", "python", "-m", "server"] } } }

接入之后，Agent 在对话过程中就能自主决定什么时候写记忆、什么时候查记忆。这里的关键是在 system prompt 里给模型清晰的指引，告诉它什么情况下该用记忆工具。比如：

当用户表达了长期偏好、重要决策或需要跨会话记住的信息时，调用 memory_write 工具。当需要回顾历史信息来回答当前问题时，调用 memory_search 工具。

没有这段指引，模型可能压根想不起来用记忆工具，那这套系统就白搭了。

5. 踩坑实录：Agent Memory 部署中最容易翻车的几个地方

5.1 Docker 网络不通的排查思路

记忆系统是多容器协作，网络问题是最常见的。典型症状是 memory-mcp 连不上 qdrant 或 postgres。

排查顺序我一般是这样的：

第一步，确认容器是否在同一网络。Docker Compose 默认会创建一个 bridge 网络，所有服务都在里面。但如果你手动docker run了某个容器，它可能不在这个网络里。用docker network inspect看容器列表。

第二步，确认服务名解析。Compose 里服务之间用服务名通信，比如http://qdrant:6333。这个服务名是 Docker 内置 DNS 解析的，前提是容器在同一网络。如果解析不了，检查服务名拼写，以及是否真的在同一网络。

第三步，确认端口监听。有时候容器起来了，但服务没监听在预期端口上。进容器里curl localhost:6333试试，或者netstat -tlnp看监听情况。

第四步，确认防火墙。宿主机防火墙有时候会拦截容器间通信，虽然不常见，但排查到最后别忘了这一层。

5.2 向量维度不匹配：一个隐蔽但致命的错误

这个坑我必须单独拎出来说，因为它太隐蔽了。

向量数据库在创建 collection 的时候，需要指定向量维度。比如你用text-embedding-3-small，维度是 1536。如果后来你换了 embedding 模型，维度变成 1024，但 collection 还是按 1536 建的，写入就会直接报错。

更坑的是，有些向量库不会明确报错，而是静默失败或者返回错误结果。你查半天查不出问题，最后才发现是维度对不上。

我的建议是：embedding 模型的配置一定要和 collection 的维度严格绑定，并且在启动时做一次校验。启动时先查 collection 的维度配置，和当前 embedding 模型的输出维度对比，不一致就直接报错退出，别让它带病运行。

5.3 记忆检索"答非所问"的调优

检索结果不相关，是记忆系统上线后最常见的反馈。原因可能有好几个，我整理成一个排查表：

这里面时间衰减是个容易被忽略的点。记忆是有时效性的，三个月前的偏好可能已经变了。检索时给记忆的相似度分数乘一个时间衰减因子，让新记忆有更高的权重，能明显改善结果的相关性。

5.4 记忆写入过多导致检索质量下降

前面提过写入过滤，这里展开说下实操。

我见过一个项目，Agent 每轮对话都把完整内容写进记忆库，跑了一周之后，记忆库几万条，检索出来的全是些"好的"、"明白了"这种废话。这就是典型的写入没有过滤。

我的做法是在写入前加一道 LLM 判断：

def should_write(content: str) -> bool: prompt = f""" 判断以下内容是否值得写入长期记忆。 值得写入的：用户偏好、重要决策、可复用的解决方案、关键事实。 不值得写入的：闲聊、确认性回复、临时状态、重复信息。 内容：{content} 只回答 yes 或 no。 """ result = llm.invoke(prompt).strip().lower() return result == "yes"

这道判断会增加一点延迟和成本，但它对记忆库质量的提升是决定性的。宁可少记，不可乱记。

5.5 MCP 工具调用失败的常见原因

MCP 工具调用失败，通常不是协议本身的问题，而是工具描述和参数定义不清晰。

我遇到过的几种情况：

• 参数类型不匹配：工具定义里top_k是 integer，模型传了个字符串 "5"，调用就失败了。解决办法是在工具描述里明确写"top_k 为整数"。
• 必填参数缺失：模型不知道某个参数是必填的，没传。解决办法是在 description 里标注 required。
• 工具描述太模糊：模型不知道什么时候该调用这个工具。解决办法是把使用场景写清楚，最好给个例子。

MCP 的调试有个技巧：把工具的完整 schema 打印出来看，确认 description、参数类型、必填项都符合预期。很多问题看一眼 schema 就明白了。

6. 记忆系统的扩展方向：从"能记住"到"会思考"

6.1 记忆的关联与图谱化

基础的记忆系统是"存-取"模型，但更高级的形态是记忆之间建立关联，形成知识图谱。

举个例子：用户说过"我在做电商项目"，后来又说过"这个项目要用 React"。这两条记忆单独看没什么，但如果建立关联——"电商项目"这个实体关联了"技术栈：React"——那么当用户问"我的项目用什么前端框架"时，系统能通过图谱直接推理出答案，而不需要靠语义相似度去碰运气。

图谱化的记忆系统，检索路径从"向量相似"变成了"关系推理"，这是质的区别。实现上可以用图数据库（如 Neo4j）来存实体和关系，配合 LLM 做实体抽取和关系构建。

6.2 记忆的主动遗忘机制

有记忆就得有遗忘。不是所有记忆都值得永久保留，过时的、错误的、低价值的记忆应该被清理。

主动遗忘可以基于几个维度：

• 时间维度：超过一定时间且从未被检索过的记忆，降低权重或归档。
• 访问频率：长期不被访问的记忆，说明价值低，可以清理。
• 冲突检测：新记忆和旧记忆冲突时，保留新的，标记或删除旧的。

这个机制听起来简单，但实现起来需要仔细设计，因为误删有价值记忆的代价很高。我的建议是采用"软删除"——先标记为失效，观察一段时间，确认没有负面影响再真正删除。

6.3 多 Agent 共享记忆的挑战

当系统里有多个 Agent 时，记忆的共享和隔离就成了新问题。

共享记忆的好处是知识复用——Agent A 学到的经验，Agent B 也能用。但风险是记忆污染——A 的错误判断可能误导 B。

隔离记忆的好处是各司其职，互不干扰。但缺点是重复学习，效率低。

实际方案通常是分层共享：通用知识放共享层，所有 Agent 都能访问；领域特定知识放各自私有层，互不干扰。这个分层怎么划，取决于具体业务场景，没有标准答案。

6.4 记忆系统的评估指标

最后说下怎么衡量记忆系统好不好。我常用的几个指标：

• 检索命中率：检索出来的记忆里，真正相关的比例。
• 检索召回率：所有相关记忆里，被检索出来的比例。
• 写入信噪比：记忆库里有效记忆和垃圾记忆的比例。
• 端到端任务成功率：接入记忆系统后，Agent 任务成功率的提升幅度。

最后一个指标最重要，因为记忆系统最终是为 Agent 任务服务的。如果任务成功率没提升，那记忆系统做得再花哨也是白搭。我建议在接入记忆系统前后，跑一批标准任务做对比，用数据说话。

这套记忆系统的搭建，从 Docker 环境到 MCP 接入，再到检索调优，整个链路我前后折腾了大概两周，中间踩的坑基本都写在上面的排查表里了。真正跑通之后最大的感受是：Agent 的记忆能力不是加个数据库就完事的，它是一套需要持续调优的系统工程。写入策略、检索算法、重排模型、时间衰减，每一个环节都影响最终效果。如果你也在做类似的东西，建议先把写入过滤和混合检索这两块做扎实，这两块的投入产出比最高。