hindsight：为LLM Agent构建可落地的记忆系统架构与实操

1. 从“hindsight”说起为什么记忆是 Agent 落地的最后一公里“hindsight”这个词本身很有意思字面意思是“事后的洞察力”也就是我们常说的“后见之明”。把它作为项目标题放在 agent memory 这个语境下指向性其实非常明确让 LLM Agent 具备对过往交互的回溯、沉淀和再利用能力。说白了就是给 Agent 装一个“能记住事、能翻旧账、能从历史里学乖”的脑子。我接触过不少做 Agent 的团队模型选型、工具调用、MCP 协议对接这些环节都跑通了demo 演示也很漂亮但一上真实业务就露馅。用户上周说过自己的偏好这周再问Agent 一脸茫然同一个任务失败过三次第四次还是踩同一个坑多轮对话稍微长一点前面聊过的关键约束就丢了。这些问题的根子都不在模型能力上而在记忆架构上。LLM 本身是无状态的每次推理都是一次性的你不主动把历史信息喂给它它就真的什么都不记得。这个项目要解决的核心问题就是给基于 LLM 的 Agent 构建一套可用的记忆系统。它适合谁看如果你正在用 MCP 协议搭 Agent、用 Docker 做本地部署、被 working memory 和长期记忆的边界搞晕过或者单纯想搞清楚“Agent 存储 working memory”到底该怎么设计那这篇内容应该能帮你少走一些弯路。我会从整体设计思路讲到具体实现包括 token 三元组的设计、MCP 协议下的记忆服务暴露、Docker 环境搭建以及我在实操中踩过的那些坑。需要先说明一点标题只给了“hindsight”这一个词所以下面的架构设计、参数选择、代码示例都是基于我在 Agent 记忆系统这个方向上的常见实践做的合理补全不是某个特定开源项目的官方文档。你可以把它当成一套可参考的落地方案按自己的业务场景调整。2. 记忆系统的整体设计与思路拆解2.1 为什么不能只靠上下文窗口硬扛很多人第一反应是现在模型上下文窗口都到 128K 甚至 1M 了把历史对话全塞进去不就行了我一开始也这么想实测下来问题一大堆。首先是成本每次推理都把几万 token 的历史重新过一遍账单会教你做人。其次是注意力稀释上下文里塞的东西越多模型对关键信息的抓取能力反而下降这在长上下文场景里是普遍现象。最后是持久性上下文窗口是会话级的会话一结束就没了跨会话的记忆根本无从谈起。所以记忆系统要解决的不是“能不能存下”而是“存什么、怎么存、什么时候取、取多少”。这四个问题决定了整个架构的形态。hindsight 这个项目的思路我理解是把记忆分成两层一层是 working memory负责当前会话内的短期上下文管理另一层是长期记忆负责跨会话的知识沉淀。两层之间通过一定的策略做流转而不是混在一起。2.2 三层记忆结构的选型考量我在实际项目里比较常用的是三层结构这里结合 hindsight 的语境展开说。第一层是working memory对应当前任务或当前会话的活跃上下文。它的特点是读写频繁、生命周期短、容量有限。实现上通常就是一个带淘汰策略的缓冲区比如保留最近 N 轮对话或者按 token 数做滑动窗口。这一层不需要持久化到数据库放在内存里就行追求的是低延迟。第二层是episodic memory也就是情景记忆记录的是“什么时候发生了什么”。比如用户在某次会话里提到了自己的项目背景、偏好设置、曾经失败过的操作。这一层需要持久化通常用向量数据库或者带索引的关系库来存。检索的时候按时间、按相似度、按实体来查。第三层是semantic memory语义记忆是从多次交互中抽象出来的稳定知识。比如“这个用户偏好简洁的回答风格”“这个任务的标准流程是 A→B→C”。这一层不是简单存原始对话而是经过提炼和归纳的。为什么这么分因为不同层的读写模式、检索方式、更新频率完全不同。混在一起会导致检索效率低下而且很难做精细化的淘汰和更新。分层的代价是架构复杂度上升但换来的是可控性和可扩展性。2.3 token 三元组key、query、value 的设计逻辑热词里有一条很关键“llm 的 token 三个点 key 我是谁、query 我在找什么、value 我能提供什么”。这其实是在讲记忆条目的结构化设计。我把它拆开讲。key我是谁是这条记忆的标识和归属。它回答的是“这条记忆属于哪个实体、哪个会话、哪个任务”。设计 key 的时候要考虑检索的入口比如用 user_id session_id timestamp 的组合或者用实体名做前缀。key 设计得好检索就能走索引快设计得差就只能全表扫描慢。query我在找什么是检索时的匹配维度。它回答的是“什么情况下应该把这条记忆取出来”。这通常是一个向量由记忆内容的 embedding 生成检索时用相似度匹配。但光有向量不够还要结合元数据过滤比如时间范围、实体类型、重要程度。value我能提供什么是记忆的实际内容。这里有个坑不要直接存原始对话文本。原始文本噪声大、冗余多检索出来还得再处理。更好的做法是存结构化或半结构化的摘要比如“用户偏好回答要简短不要用列表”这种提炼后的形式。这三者组合起来一条记忆就是一个可检索、可过滤、可更新的单元。我实测下来这种结构比单纯存文本向量的召回准确率高不少尤其是在多用户、多任务的场景下。2.4 MCP 协议在记忆系统中的角色MCP 是 Model Context Protocol一种让模型和外部工具、数据源对接的协议。热词里有人问“mcp 是软件协议还是硬件协议那个概念叫什么来着”这里顺带说清楚MCP 是软件层面的协议跟硬件没关系它定义的是模型怎么发现和调用外部能力。在 hindsight 这个场景里MCP 的价值在于把记忆系统做成一个独立的服务通过 MCP 暴露给 Agent。这样做的好处是解耦记忆的存储、检索、更新逻辑都在服务端Agent 只需要通过标准协议调用就行。换模型、换 Agent 框架记忆服务不用动。具体来说可以定义几个 MCP toolmemory_store用于写入记忆memory_retrieve用于检索memory_update用于更新memory_forget用于删除。Agent 在对话过程中根据需要调用这些工具。这样记忆的管理就变成了一个可观测、可调试的独立环节而不是埋在 Agent 代码里的黑盒。3. 核心细节解析与实操要点3.1 working memory 的容量与淘汰策略working memory 的容量设置是个经验活。设太小关键信息留不住设太大成本和延迟都上去了。我的做法是按 token 数设上限而不是按轮数。因为一轮对话可能很短也可能很长按轮数不准确。具体参数上我一般把 working memory 控制在 2000 到 4000 token 之间。这个范围能覆盖大多数任务的关键上下文又不至于让每次推理的输入过长。淘汰策略用 LRU最近最少使用结合重要性加权最近用到的保留被频繁引用的保留其他的淘汰。这里有个细节淘汰的时候不要直接丢弃而是把被淘汰的内容压缩后转入 episodic memory。这样既释放了 working memory 的空间又不会丢失信息。压缩可以用一个小模型做摘要或者用规则提取关键实体和结论。注意working memory 的淘汰一定要有日志。我踩过的坑是淘汰逻辑写错了把重要信息丢了但没有任何记录排查了半天才发现。后来加了淘汰日志每次淘汰都记录淘汰了什么、为什么淘汰问题一目了然。3.2 记忆写入的时机与去重什么时候往长期记忆里写这个问题比想象中难。写太频繁噪声大写太少关键信息漏掉。我的策略是事件驱动加定期归纳。事件驱动的触发条件包括用户明确表达了偏好或约束、任务完成或失败、出现了新的实体或概念、用户纠正了 Agent 的错误。这些时刻的信息价值高值得立即写入。定期归纳则是每隔一段时间比如每 10 轮对话或者会话结束时把这段时间的交互做一次摘要提炼出稳定的知识写入 semantic memory。去重是个大问题。同一个信息可能被多次写入导致检索时重复召回。我的做法是在写入前先做一次相似度检查如果已有高度相似的记忆就更新而不是新增。相似度阈值我一般设在 0.85 左右太低会误合并太高会漏合并。3.3 检索策略向量加元数据的混合召回单纯用向量检索的问题在于它只考虑语义相似度不考虑时效性、重要性和实体匹配。实际场景里用户问“我上次说的那个配置”向量检索可能召回一堆语义相近但时间不对的记忆。我的做法是混合召回先用元数据做粗筛比如限定 user_id、时间范围、记忆类型然后在候选集里做向量相似度排序。这样既保证了相关性又保证了准确性。排序的时候还要加权重。时间越近权重越高被引用次数越多权重越高重要程度标记越高权重越高。最终得分是相似度、时效性、重要性、引用次数的加权和。权重怎么设我一般用 0.5、0.2、0.2、0.1 作为初始值然后根据业务反馈调。维度权重初始值调整方向语义相似度0.5召回不准时提高时效性0.2用户在意最新信息时提高重要性0.2关键信息漏召回时提高引用次数0.1高频信息优先时提高3.4 记忆的更新与遗忘机制记忆不是写完就不管了。过时的信息要更新错误的信息要修正无用的信息要遗忘。hindsight 这个名字本身就暗示了“事后修正”的能力。更新机制上我给每条记忆加一个版本号和一个置信度。当新信息与旧记忆冲突时不是直接覆盖而是新增一条并降低旧记忆的置信度。检索时优先返回高置信度的。这样保留了历史也避免了错误信息主导。遗忘机制上我设置了一个衰减函数记忆的权重随时间衰减如果长时间没有被检索到权重降到阈值以下就归档或删除。衰减的速率可以按记忆类型区分比如用户偏好衰减慢临时任务状态衰减快。提示遗忘一定要可配置、可回滚。我遇到过衰减参数设得太激进把用户半年前的重要偏好删了用户投诉。后来改成先归档再删除归档保留 90 天给了缓冲期。4. 实操过程与核心环节实现4.1 Docker 环境准备与依赖服务搭建记忆系统依赖几个基础服务向量数据库、关系数据库、缓存。用 Docker 部署是最省事的。下面是我常用的 docker-compose 配置思路。先拉取镜像。向量数据库我用 Qdrant关系库用 PostgreSQL缓存用 Redis。这三个都有官方镜像直接 pull 就行。version: 3.8 services: qdrant: image: qdrant/qdrant:latest ports: - 6333:6333 volumes: - ./qdrant_data:/qdrant/storage postgres: image: postgres:16 environment: POSTGRES_PASSWORD: yourpassword POSTGRES_DB: memory ports: - 5432:5432 volumes: - ./pg_data:/var/lib/postgresql/data redis: image: redis:7-alpine ports: - 6379:6379启动命令就是docker compose up -d。这里有个坑Windows 上装 Docker Desktop 经常遇到 “virtualization support not detected” 的报错原因是 BIOS 里的虚拟化支持没开。进 BIOS 把 Intel VT-x 或 AMD-V 打开就行。另外 WSL2 要装好Docker Desktop 依赖它。注意数据卷一定要挂载到宿主机不然容器一删数据就没了。我早期图省事没挂载重装容器后记忆全丢血的教训。4.2 记忆服务的核心接口实现记忆服务用 Python 写FastAPI 做 HTTP 接口同时通过 MCP 协议暴露工具。核心接口有四个store、retrieve、update、forget。store 接口的逻辑是接收记忆内容、类型、元数据先做去重检查然后生成 embedding写入向量库和关系库。async def store_memory(content: str, mem_type: str, metadata: dict): # 去重检查 existing await find_similar(content, threshold0.85) if existing: return await update_memory(existing.id, content, metadata) # 生成 embedding embedding await embed(content) # 写入向量库 vector_id await qdrant.upsert(embedding, metadata) # 写入关系库 await pg.insert(memories, { vector_id: vector_id, content: content, type: mem_type, metadata: metadata, confidence: 1.0, created_at: now() }) return vector_idretrieve 接口的逻辑是先按元数据粗筛再做向量检索最后加权排序返回 top-k。async def retrieve_memory(query: str, filters: dict, top_k: int 5): query_vec await embed(query) # 元数据粗筛 candidates await pg.query(memories, filters) # 向量检索 results await qdrant.search(query_vec, limittop_k * 3) # 加权排序 scored [] for r in results: score (0.5 * r.similarity 0.2 * time_decay(r.created_at) 0.2 * r.importance 0.1 * r.ref_count) scored.append((score, r)) scored.sort(reverseTrue) return [r for _, r in scored[:top_k]]update 和 forget 相对简单update 是新增版本并降低旧版本置信度forget 是标记归档或删除。4.3 MCP 工具的定义与 Agent 对接MCP 工具的定义要遵循协议规范。每个工具要有 name、description、input schema。description 要写清楚什么时候用这个工具因为模型是根据 description 来决定调不调的。{ name: memory_retrieve, description: 检索与当前对话相关的历史记忆。当用户提到过去的信息、偏好或之前做过的事情时调用。, inputSchema: { type: object, properties: { query: {type: string, description: 检索查询描述你在找什么}, filters: {type: object, description: 过滤条件如用户ID、时间范围} }, required: [query] } }Agent 对接的时候在系统提示里要说明记忆工具的存在和使用时机。我一般会写“你有记忆能力当用户提到过去的信息时先调用 memory_retrieve 检索再基于检索结果回答。”这样模型才知道什么时候该用。实测下来工具 description 的质量直接决定了调用准确率。description 写得太泛模型会乱调写得太窄该调的时候不调。我的经验是 description 里要包含具体的触发场景举例。4.4 参数计算与性能调优embedding 模型的选择影响很大。我一般用 768 维或 1024 维的模型维度太低表达能力不够太高存储和检索成本上去了。768 维在大多数场景下够用。向量检索的 ef 参数HNSW 索引的搜索范围我一般设 128。设太小召回率低设太大延迟高。这个值可以根据实际数据量调数据量大的时候适当提高。working memory 的 token 上限我前面说了是 2000 到 4000。具体怎么定我的方法是统计典型任务的对话长度取 P90 分位数作为上限。这样能覆盖 90% 的任务又不至于浪费。检索的 top_k 我一般设 5。返回太多会稀释关键信息返回太少可能漏掉。5 是个比较平衡的值实测下来效果稳定。5. 常见问题与排查技巧实录5.1 记忆召回不准的排查思路召回不准是最常见的问题表现是明明存了相关信息检索的时候就是出不来。排查要分几步走。先看 embedding 有没有问题。把查询和记忆内容分别 embed算一下余弦相似度如果相似度很低说明 embedding 模型不适合这个场景要换模型。再看元数据过滤是不是太严。有时候 filter 条件设得太细把相关记忆筛掉了。可以先把 filter 放宽看召回有没有改善。最后看排序权重。如果相似度高的记忆排在后面说明权重设置有问题。可以打印出候选集的各项得分看看是哪一项拖了后腿。现象可能原因排查方法完全召不回embedding 不匹配手动算相似度召回但排序靠后权重设置不当打印各项得分召回不相关元数据过滤失效检查 filter 条件召回重复去重逻辑失效检查相似度阈值5.2 Docker 网络与容器通信问题Docker 容器之间通信是另一个高频坑。默认情况下同一个 compose 网络里的容器可以用服务名互相访问。但如果配置不对会出现网络不通。我遇到过的情况是记忆服务容器连不上 Qdrant报连接超时。排查发现是 Qdrant 的端口映射写错了容器内部端口和宿主机端口搞混了。容器之间通信用的是内部端口不是映射到宿主机的端口。还有一个坑是 Docker Desktop 在 Windows 上的网络模式。默认的 bridge 模式有时候会有 DNS 解析问题导致服务名解析不了。解决办法是在 compose 里显式指定 network或者用 host 模式但 host 模式在 Windows 上支持有限。提示排查容器网络问题先用docker exec进容器用ping和curl测试连通性。能 ping 通但 curl 不通多半是端口或协议问题。5.3 记忆膨胀与性能下降系统跑一段时间后记忆库越来越大检索变慢这是必然的。要提前做容量规划。我的做法是分层存储热数据最近 30 天放高性能存储温数据30 天到 1 年放普通存储冷数据1 年以上归档到对象存储。检索时默认只查热数据需要时再查温数据。另外要定期做记忆压缩。把多条相关的细粒度记忆合并成一条粗粒度的减少条目数。比如用户多次提到喜欢简洁回答可以合并成一条“用户偏好简洁风格”。5.4 常见问题速查表问题症状解决方向记忆丢失重启后记忆没了检查数据卷挂载检索超时查询响应慢检查索引、减少 top_k重复召回同一信息返回多次加强去重、合并相似记忆工具不调用Agent 不用记忆工具优化 tool description上下文溢出推理报 token 超限压缩 working memory置信度混乱新旧信息冲突检查版本和置信度逻辑5.5 我踩过的几个典型坑第一个坑是 embedding 模型换了之后没重新索引。换了模型向量的语义空间变了旧向量和新查询对不上召回全乱。换模型一定要全量重建索引。第二个坑是 working memory 淘汰没做压缩。直接丢弃导致信息断层Agent 在对话中途突然“失忆”。后来改成淘汰前先摘要把摘要转入长期记忆问题解决。第三个坑是 MCP 工具的 description 写得太技术化。模型看不懂“检索记忆条目”这种表述后来改成“当用户提到之前说过的事情时用这个工具查找”调用率明显上升。第四个坑是没做记忆的时效性管理。用户三个月前说的偏好现在还当有效信息用导致回答不符合用户当前需求。后来加了时效性权重老记忆的权重自动衰减。6. 记忆系统的扩展方向与个人体会这套架构跑通之后可以扩展的方向不少。一个是多模态记忆把图片、音频也纳入记忆体系这需要多模态 embedding 模型的支持。另一个是记忆的主动学习让 Agent 自己判断哪些信息值得记、哪些该忘减少人工规则。还有一个方向是记忆的共享与隔离。多 Agent 协作的场景下哪些记忆该共享、哪些该隔离是个需要仔细设计的问题。我的初步想法是按任务和角色做权限控制但还没在真实场景里验证过。我个人在实际操作中的体会是记忆系统的难点不在技术实现而在策略设计。存什么、什么时候存、怎么检索、什么时候忘这些策略的优劣直接决定了系统的可用性。技术方案可以抄策略得自己磨。我建议刚开始不要追求大而全先把 working memory 和一层长期记忆做扎实跑通闭环再逐步加层。上来就搞三层五层大概率会陷在复杂度里出不来。最后分享一个小技巧给记忆系统加一个调试接口能手动查看某条记忆的完整生命周期——什么时候写入、被检索过几次、当前权重多少、有没有被更新过。排查问题的时候这个接口比看日志高效得多。