1. 为什么“hindsight”是 Agent Memory 最值得啃的一块硬骨头“hindsight”这个词本身就有意思——事后诸葛亮、后见之明。放在 Agent Memory 这个语境里它指向的其实是一个很具体的问题智能体在完成任务之后能不能回过头来把这次经历里真正有用的东西沉淀下来而不是每次对话都从零开始。我接触 agent memory 这条线大概是从去年下半年开始的当时市面上大多数方案还停留在“把历史对话塞进向量库检索 top-k 拼进 prompt”这个阶段。说实话这套东西跑 demo 没问题一旦上真实业务就露馅检索出来的记忆要么是无关的闲聊要么是过期的状态要么干脆把互相矛盾的信息一起喂给模型导致 LLM 输出前后不一致。hindsight 想解决的就是这个——它不是简单的“存和取”而是让 agent 具备事后复盘并结构化沉淀记忆的能力。这个项目适合谁看如果你正在做基于 LLM 的 agent 应用尤其是那种需要跨会话保持状态、需要长期积累经验的场景客服、运维助手、个人助理、代码 agent那 hindsight 这套思路你绕不开。如果你只是调用 API 做单轮问答那可以先收藏等业务复杂了再回来。本文会从设计思路、核心机制、Docker 部署、MCP 集成、常见坑几个维度把它拆透尽量做到你照着就能复现。需要先说明一点hindsight 目前没有一个官方统一的“标准实现”它更像是一类设计范式的统称社区里有多种落地形态。我下面讲的是基于常见实践总结出来的一套可复现方案核心逻辑是通用的具体实现你可以按自己的技术栈调整。2. Agent Memory 的整体设计与 hindsight 的定位2.1 传统记忆方案的三个致命短板在讲 hindsight 之前得先把“为什么现有方案不够用”说清楚不然你没法理解它为什么要这么设计。第一个短板是“无差别存储”。大多数方案把用户说的每句话、agent 的每次回复都往向量库里扔。结果就是记忆库迅速膨胀检索信噪比急剧下降。我实测过一个客服 agent跑了两周记忆库里 80% 是“好的”“谢谢”“稍等”这类无信息量的内容真正有价值的“用户偏好”“历史故障”“已确认的解决方案”被淹没在里面。第二个短板是“状态与知识混在一起”。Agent 的记忆其实分两类一类是状态型记忆working memory比如“当前任务进行到第几步”“用户刚才确认了哪个选项”另一类是知识型记忆long-term memory比如“这个用户偏好邮件沟通”“上次这类报错的根因是配置项 X”。这两类的生命周期、检索方式、更新策略完全不同混在一个库里必然出问题。第三个短板是“只存不反思”。这是最关键的。传统方案是“发生什么存什么”而 hindsight 的核心是“任务结束后回头看看哪些值得存、以什么形式存”。这个“事后复盘”的动作才是 hindsight 名字的由来。2.2 hindsight 的核心设计哲学hindsight 的设计可以概括成一句话记忆不是日志是结论。它不追求把过程完整记录下来而是追求在任务节点结束后提炼出可复用的结论。具体来说它把记忆的写入时机从“每轮对话”改成了“任务里程碑或任务结束”把记忆的内容从“原始文本”改成了“结构化条目”把记忆的检索从“纯向量相似度”改成了“向量 元数据过滤 时效衰减”的混合策略。这个转变带来的直接好处是记忆库增长慢、信噪比高、检索准。代价是需要设计一套“什么时候触发复盘”“复盘时提取什么”的机制这部分是 hindsight 实现里最需要花心思的地方。2.3 为什么用 Docker MCP 这套组合热词里同时出现了 Docker 和 MCP这不是偶然。hindsight 这类记忆服务天然适合做成独立进程 标准协议的形态。用 Docker 的理由很直接记忆服务需要持久化存储向量库 关系库需要独立的资源配额需要能随时重启而不影响主 agent。把它容器化agent 通过 HTTP 或 MCP 调用解耦得干干净净。我试过把记忆逻辑直接写在 agent 进程里结果是 agent 一重启记忆就乱调试时也没法单独看记忆服务的日志非常痛苦。用 MCP 的理由更本质MCP 是一套让 LLM 应用和外部工具/数据源对接的协议。把 hindsight 包装成 MCP server意味着任何支持 MCP 的客户端Claude Desktop、各类 IDE 插件、自研 agent 框架都能直接调用记忆能力不用为每个客户端写一遍适配。这就是协议的价值——一次实现处处可用。3. 核心机制拆解hindsight 到底怎么“事后复盘”3.1 记忆的三层结构我把 hindsight 的记忆结构拆成三层这个划分是我在实际项目里验证过最顺手的层级名称生命周期存储介质典型内容L1Working Memory单次会话内存/Redis当前任务状态、临时变量、最近几轮上下文L2Episodic Memory数天到数周关系库 向量库任务摘要、关键决策、结果L3Semantic Memory长期向量库 图结构用户偏好、领域知识、稳定结论L1 是 working memory热词里提到的“agent 存储 working memory”说的就是它。它的特点是读写极频繁、容量小、会话结束就清。我一般用 Redis 存key 设计成wm:{session_id}:{slot}过期时间设成会话超时时间的两倍防止边界情况丢状态。L2 是情景记忆每次任务结束由 hindsight 的复盘模块写入。它记录的是“这次任务发生了什么、结论是什么”带时间戳和任务 ID可以按时间线回溯。L3 是语义记忆是从多条 L2 里归纳出来的稳定知识。比如用户连续三次都选了“邮件通知”L3 里就会沉淀一条“该用户偏好邮件通知”。L3 的写入需要触发条件不能每条 L2 都往 L3 写否则就退化成无差别存储了。3.2 复盘触发机制什么时候该“回头看”这是 hindsight 最关键的设计点。触发太频繁等于每轮都存退化成传统方案触发太少重要经验会丢。我实践下来有三种触发方式配合使用第一种是任务边界触发。当 agent 判断当前任务完成或失败时触发一次完整复盘。判断任务边界可以靠显式的结束信号用户说“搞定”“谢谢”也可以靠 agent 自己的规划模块判断。这是最主要的触发方式。第二种是里程碑触发。长任务中途的关键节点比如“已确认需求”“已定位根因”触发一次轻量复盘只写 L2 不写 L3。第三种是定时/定量触发。每 N 轮对话或每 M 分钟强制复盘一次防止长会话里任务边界不清晰导致记忆丢失。注意触发机制一定要有“去重”逻辑。我踩过的坑是用户连续说“好的好的好的”触发了三次复盘写了三条几乎一样的记忆。后来加了个规则如果本次复盘提取的结论和最近一条 L2 的相似度超过阈值我用 0.92就合并而不是新增。3.3 复盘时提取什么从原始对话到结构化条目复盘模块本身也是一次 LLM 调用prompt 的设计直接决定记忆质量。我的 prompt 模板大致是这样的结构你是一个记忆提炼器。下面是刚刚结束的一段任务对话。 请提取以下三类信息以 JSON 输出 1. facts: 客观事实用户身份、环境信息、已确认的参数 2. decisions: 做出的决策及理由 3. outcomes: 任务结果成功/失败、关键产物、遗留问题 要求 - 只提取对未来任务有复用价值的信息 - 忽略寒暄、重复确认、无信息量的内容 - 每条信息控制在 50 字以内 - 如果某类没有内容返回空数组这个 prompt 的关键在于“只提取有复用价值的信息”这句约束。不加这句模型会把所有内容都提取出来加了之后它会主动过滤掉噪音。实测下来加了这句约束后记忆条目的有效率从大概 40% 提升到了 75% 以上。提取出来的 JSON 再经过一层处理facts 和 decisions 写入 L2outcomes 里的成功经验尝试归纳进 L3。归纳进 L3 时要做冲突检测——如果新结论和已有 L3 矛盾标记为“待确认”不直接覆盖。3.4 检索策略为什么纯向量不够用检索这块纯向量相似度的问题在于它只看语义接近不看时效和重要性。一个三个月前的临时结论和一个昨天的稳定偏好向量相似度可能差不多但显然应该优先返回后者。我的混合检索策略是最终得分 向量相似度 × 时效衰减系数 × 重要性权重。时效衰减系数用指数衰减半衰期设成 14 天这个值按业务调客服场景可以短一点个人助理可以长一点。重要性权重在写入时由复盘模块打分1-5检索时归一化。这样即使一个旧记忆语义很接近只要时效衰减够狠也不会挤掉新的重要记忆。提示向量库选型上如果记忆量在百万级以内pgvector 完全够用而且能和关系库放一起运维简单。超过百万级再考虑专门的向量库。我一开始就上了专用向量库结果发现数据量根本没到那个级别白白增加了运维复杂度。4. Docker 部署 hindsight 记忆服务完整实操4.1 环境准备与 Docker 安装要点先把 Docker 环境搞定。Windows 用户注意Docker Desktop 依赖 WSL2 或 Hyper-V安装前确认虚拟化在 BIOS 里开了。热词里那个 “virtualization support not detected” 的报错九成是 BIOS 里虚拟化没开或者和 Hyper-V 冲突了。Windows 11 装 Docker Desktop 的流程先去官网下安装包安装时勾选 “Use WSL 2 instead of Hyper-V”装完重启。如果启动报错打开 PowerShell 跑wsl --update更新 WSL 内核再重启 Docker Desktop。这个坑我踩过卡了半小时才发现是 WSL 内核太旧。Linux 用户直接用官方脚本装就行curl -fsSL https://get.docker.com | sh sudo systemctl enable docker sudo systemctl start docker装完验证一下docker --version docker compose version两个命令都有输出才算 OK。docker compose 现在是 v2命令是docker compose中间空格不是老的docker-compose这个别搞混。4.2 记忆服务的 docker-compose 编排hindsight 记忆服务我建议拆成三个容器PostgreSQL带 pgvector、Redis、记忆服务本体。用 docker-compose 编排一份文件搞定。version: 3.9 services: pg: image: pgvector/pgvector:pg16 container_name: hindsight-pg environment: POSTGRES_USER: hindsight POSTGRES_PASSWORD: hindsight_pwd POSTGRES_DB: hindsight ports: - 5433:5432 volumes: - ./data/pg:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U hindsight] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: hindsight-redis ports: - 6380:6379 volumes: - ./data/redis:/data command: redis-server --appendonly yes memory: build: ./memory-service container_name: hindsight-memory depends_on: pg: condition: service_healthy redis: condition: service_started environment: PG_DSN: postgresql://hindsight:hindsight_pwdpg:5432/hindsight REDIS_URL: redis://redis:6379/0 EMBEDDING_MODEL: text-embedding-3-small DECAY_HALFLIFE_DAYS: 14 ports: - 8088:8088 volumes: - ./data/logs:/app/logs几个关键点解释一下。端口我故意错开了默认端口pg 用 5433redis 用 6380避免和你机器上已有的服务冲突这个习惯能省很多事。healthcheck 是必须的memory 服务依赖 pg 就绪不加 healthcheck 的话 memory 启动时 pg 还没起来直接报连接失败。DECAY_HALFLIFE_DAYS这个环境变量控制时效衰减半衰期我默认给 14 天你可以按业务调。4.3 数据库初始化与向量扩展pgvector 扩展需要手动启用容器起来后执行docker exec -it hindsight-pg psql -U hindsight -d hindsight -c CREATE EXTENSION IF NOT EXISTS vector;然后建表。核心是两张表episodic_memory和semantic_memory。CREATE TABLE episodic_memory ( id BIGSERIAL PRIMARY KEY, session_id TEXT NOT NULL, task_id TEXT, content TEXT NOT NULL, category TEXT, importance INT DEFAULT 3, embedding vector(1536), created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE INDEX ON episodic_memory USING ivfflat (embedding vector_cosine_ops) WITH (lists 100); CREATE INDEX ON episodic_memory (session_id, created_at DESC); CREATE TABLE semantic_memory ( id BIGSERIAL PRIMARY KEY, content TEXT NOT NULL, category TEXT, confidence REAL DEFAULT 0.5, embedding vector(1536), updated_at TIMESTAMPTZ DEFAULT NOW() );vector(1536)对应 text-embedding-3-small 的维度。如果你换模型维度要跟着改这个别搞错否则插入直接报错。ivfflat 索引的lists参数经验值是行数的平方根数据量小的时候给 100 就行。4.4 启动与健康检查编排文件写好构建并启动docker compose up -d --build docker compose ps三个容器都 Up 且 pg 是 healthy 才算成功。然后测一下记忆服务的健康接口curl http://localhost:8088/health返回{status:ok,pg:ok,redis:ok}就说明链路通了。如果 pg 显示 error八成是 DSN 写错了或者 pgvector 扩展没建。注意docker compose down默认不删数据卷数据是安全的。但如果你手贱加了-v参数数据卷会被一起删掉记忆全没。这个参数我建议你永远别用除非确定要清库。5. MCP 集成让任意 LLM 客户端用上 hindsight5.1 MCP 是什么为什么值得接MCP 本质上是一套标准化的“工具调用协议”它规定了 LLM 应用怎么发现工具、怎么调用工具、怎么拿回结果。你可以把它类比成 USB 接口——不管你是键盘、鼠标还是 U 盘只要符合 USB 标准插上就能用。MCP 就是 LLM 世界的 USB。把 hindsight 包装成 MCP server 之后任何支持 MCP 的客户端都能调用记忆能力。这意味着你写一次记忆服务Claude Desktop 能用、IDE 插件能用、自研 agent 也能用。热词里提到的 “codex 接入 mcp”“dify 浏览器 mcp” 都是这个思路的延伸。5.2 把 hindsight 暴露成 MCP serverMCP server 的核心是定义 tools。hindsight 我暴露四个工具# memory_mcp_server.py from mcp.server import Server from mcp.types import Tool, TextContent import httpx app Server(hindsight-memory) MEMORY_API http://localhost:8088 app.list_tools() async def list_tools(): return [ Tool( namememory_write, description写入一条记忆。任务结束或里程碑时调用。, inputSchema{ type: object, properties: { session_id: {type: string}, content: {type: string}, category: {type: string, enum: [fact, decision, outcome]}, importance: {type: integer, minimum: 1, maximum: 5} }, required: [session_id, content, category] } ), Tool( namememory_search, description检索相关记忆。任务开始或需要上下文时调用。, inputSchema{ type: object, properties: { query: {type: string}, session_id: {type: string}, top_k: {type: integer, default: 5} }, required: [query] } ), Tool( namememory_reflect, description触发一次复盘从对话历史中提炼记忆。, inputSchema{ type: object, properties: { session_id: {type: string}, conversation: {type: string} }, required: [session_id, conversation] } ), Tool( nameworking_memory_set, description设置 working memory 槽位。, inputSchema{ type: object, properties: { session_id: {type: string}, slot: {type: string}, value: {type: string} }, required: [session_id, slot, value] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): async with httpx.AsyncClient() as client: if name memory_write: r await client.post(f{MEMORY_API}/memory/write, jsonarguments) elif name memory_search: r await client.post(f{MEMORY_API}/memory/search, jsonarguments) elif name memory_reflect: r await client.post(f{MEMORY_API}/memory/reflect, jsonarguments) elif name working_memory_set: r await client.post(f{MEMORY_API}/wm/set, jsonarguments) else: return [TextContent(typetext, textfunknown tool: {name})] return [TextContent(typetext, textr.text)]这段代码的关键在于工具描述要写清楚“什么时候调用”。MCP 客户端也就是 LLM是根据 description 来决定调不调、什么时候调的。memory_write的描述里写“任务结束或里程碑时调用”模型就会在合适的时机触发而不是每轮都写。5.3 客户端配置与授权以 Claude Desktop 为例配置文件里加一段{ mcpServers: { hindsight: { command: python, args: [/path/to/memory_mcp_server.py], env: { MEMORY_API: http://localhost:8088 } } } }重启客户端如果工具列表里出现了四个 memory 工具就说明接上了。热词里提到的 “codex 无法找到 mcp” 这类问题九成是路径写错或者 Python 环境不对。建议用绝对路径并且确认python命令指向的环境里装了 mcp 和 httpx。提示MCP server 的日志默认打到 stderr客户端一般会把它收进自己的日志文件。调试时先看客户端日志别急着改代码。我遇到过工具明明注册了但客户端不显示最后发现是 server 启动时抛了个 import 错误日志里写得清清楚楚。5.4 working memory 与 MCP 的配合working memory 这块我建议不要走 MCP 的 memory_write而是单独用working_memory_set工具。原因是 working memory 读写太频繁走复盘流程太重。直接 set/get走 Redis毫秒级返回。Agent 的典型调用顺序是任务开始时memory_search拉相关长期记忆 working_memory_set初始化任务状态任务过程中working_memory_set更新状态任务结束时memory_reflect触发复盘。这个顺序跑顺了agent 的“记忆感”就出来了。6. 常见问题与排查技巧实录6.1 记忆检索不准的排查路径检索不准是最常见的问题排查按这个顺序来现象可能原因排查方法解决返回无关记忆embedding 模型不一致检查写入和检索用的模型是否同一个统一模型重建索引旧记忆挤掉新记忆时效衰减没生效打印检索得分明细检查衰减系数计算重要记忆检索不到重要性权重太低查该条记忆的 importance复盘时提高打分检索结果为空向量维度不匹配查表定义和模型维度对齐维度我遇到最多的是“embedding 模型不一致”。写入时用 A 模型检索时用 B 模型向量空间都不一样检索结果自然离谱。这个坑很隐蔽因为两边都不报错只是结果不对。建议在记忆服务启动时打印一次当前 embedding 模型名方便核对。6.2 Docker 网络不通的典型场景Docker 网络问题我总结了三类第一类是容器间不通。同一个 compose 网络里的容器用服务名互相访问不要用 localhost。memory 服务连 pgDSN 里写的是pg:5432而不是localhost:5432这个别搞错。第二类是宿主机访问容器不通。检查端口映射ports里写的是宿主机端口:容器端口顺序别反。我见过有人写成5432:5433然后一直连不上查了半天。第三类是容器访问外网不通。一般是 DNS 问题在 compose 里给服务加dns: 8.8.8.8试试。如果是公司内网可能要配代理这个按实际环境来。6.3 复盘质量差的调优经验复盘质量差表现为提取出来的记忆要么太碎、要么太泛。调优主要调三处prompt 里的约束。“每条信息控制在 50 字以内”这个约束很关键不加的话模型会写一大段。但也不能太短太短会丢信息。50 字是我试出来比较平衡的值。importance 打分标准。要在 prompt 里明确告诉模型什么算 5 分什么算 1 分。我的标准是影响后续所有任务的算 5 分只影响当前任务的算 1 分。不明确标准模型打分很随机。去重阈值。相似度阈值设太高重复记忆多设太低不同记忆被误合并。0.92 是我试出来的经验值你可以从这个值开始调。6.4 记忆膨胀的控制手段跑久了记忆库膨胀是必然的控制手段有三个定期归档。超过 90 天且 importance 低于 3 的 L2 记忆归档到冷存储不参与检索。这个用定时任务做每周跑一次。L3 归纳压缩。多条相似的 L2 归纳成一条 L3然后把这些 L2 标记为已归纳检索时降权。这样记忆库不会无限增长。容量告警。给记忆库设个容量阈值超过就告警提醒你该清理了。我设的是 50 万条到了就人工介入。注意归档和删除是两回事。归档是移到冷存储还能查删除是真没了。我建议永远只归档不删除除非你确定那条记忆是错的。记忆这东西删错了比留着更麻烦。7. 我在实际项目里踩过的几个坑第一个坑是把 working memory 也持久化了。一开始图省事working memory 也写进了 pg结果会话结束后这些临时状态还在下次会话检索时被捞出来agent 一脸懵。后来改成 Redis 过期时间问题解决。working memory 就该是易失的别持久化。第二个坑是复盘触发太频繁。早期版本每轮对话都触发复盘结果 LLM 调用量暴涨成本扛不住而且记忆质量还差。改成任务边界触发后调用量降了 80%质量反而上去了。这个教训是记忆的价值在于提炼不在于记录。第三个坑是MCP 工具描述写得太模糊。一开始memory_write的描述就写了“写入记忆”结果模型不知道什么时候该调要么不调要么乱调。后来把触发时机写进描述里模型的行为立刻规范了。MCP 工具的描述就是给模型看的说明书写得越清楚模型用得越准。第四个坑是没做冲突检测。有次用户先说了“偏好电话沟通”后来说“还是邮件吧”两条 L3 都存进去了检索时随机返回一条agent 行为不一致。后来加了冲突检测新结论和旧结论矛盾时标记待确认人工或高置信度才覆盖。记忆的一致性比记忆的数量重要得多。这套东西跑顺之后我的 agent 跨会话的连贯性明显上来了用户不用每次重复背景agent 也能记住之前的偏好和结论。hindsight 这个名字起得确实贴切——让 agent 学会回头看比让它拼命往前跑更有价值。