HindsightAgent 长期记忆系统设计与实现前言最近在调研 Agent 长期记忆方案看了几个开源项目Hindsight 是其中设计比较完整的一个。它把会话内容提取成结构化事实再通过后台的合并流程把重复事实收敛成带证据的结论让记忆库随使用时间变得更准确避免单纯堆积带来的噪声累积问题。这里整理一下它的设计思路、实测情况和适用范围。素材来自官方文档、源码阅读和本机部署实测数据快照时间为 2026-10-05。一、项目简介项值仓库https://github.com/vectorize-io/hindsight官方文档https://hindsight.vectorize.io/论文https://arxiv.org/abs/2512.12818Star / Fork45,966 / 5,933语言 / 许可证Python / MIT创建时间2025-10-30最新版本v0.10.22026-09-29存储后端PostgreSQL pgvector默认内嵌 pg0或 Oracle AI Database 23ai对外接口只有三个retain写入。把输入内容提取成结构化事实。recall检索。返回排序后的记忆。reflect反思。基于记忆库内容生成结论。记忆以 bank 为单位隔离一个用户、一个 Agent 或一个项目对应一个 bankbank 之间不共享数据。二、记忆结构设计Hindsight 把记忆分为四层层内容生成方式World facts客观事实retain 时由 LLM 提取ExperiencesAgent 自身经历retain 时由 LLM 提取Observations由多条事实合并得到的结论带证据引用和证明计数后台 consolidation 生成Mental models针对固定问题的常驻答案也叫知识页reflect 生成并持续刷新四层之间是演进关系写入时从原始事实向上聚合检索时从高层的结论向下查找。实现上有两点需要注意。1. 事实与经验的区分依据是叙述视角。LLM 在提取时只能输出 world 和 assistant 两种类型其中 assistant 在落库前由代码转换为 experience。实测中今天处理了 XX 故障根因是 XX这类第三人称叙述会被判为 world我先询问助手 X助手回复 Y我按此修改后仿真通过这类包含交互过程的叙述会被判为 experience。因此如果要让 experience 类型的数据出现输入应当是交互式对话记录总结性文档通常只会产生 world。2. 两类记忆在检索中权重相同。experience 不是低优先级数据它和 world 一样参与全部四路检索也同样作为 observation 的证据来源。差异只在默认检索范围recall 不指定类型时默认查询 world 和 experience。三、知识演化1. 写入时完成合并常见做法是记忆只增不改冲突留到查询阶段处理。Hindsight 把这一步提前到写入阶段每次 retain 完成后后台自动触发 consolidation由 LLM 批量判断新事实应该新建、合并还是删除。合并规则中有三条比较关键UPDATE 优先于 CREATE。同一条结论被多次提到时合并为一条避免保留多条重复记录。官方文档的表述是一条带 100 个 source facts 的规范 observation优于 100 条重复记录。NO COMPUTATION。禁止 LLM 自行推算数值。例如输入我有 2 条狗和其中一条叫 Rex不允许推导出共有 3 只宠物。PRESERVE HISTORY。重要结论不删除删除仅限被直接取代或明确矛盾的情况。合并结果由 SQL 语义保证不依赖提示词证据取并集时间范围取 LEAST 和 GREATEST 单调扩展证明计数按来源数量重算旧文本写入 history 表做快照。2. 证据链每条 observation 记录三样数据字段含义source_memory_ids支撑该结论的原始事实 ID 列表proof_count独立证据的数量history每次改写前的文本快照这三样数据让记忆可以追溯和撤回能查询某条结论对应哪些原始记录原始记录作废时派生的结论会被级联清理并重新合并错误知识可以沿引用链定向撤回。向量数据库在结构上无法提供这类能力。实测中可以看到具体表现。同一条 observation 在第三次被同义重述后proof_count 由 1 变为 2来源 ID 列表追加一条文本被改写但信息未丢失history 新增一条完整快照。3. 知识页mental model 用于降低高频问题的重复检索和推理开销。指定一个问题后后台会将其写成一份 Markdown 文档并随新证据自动刷新。读取时只需要一次数据库查询不涉及检索和 LLM 调用。刷新采用增量方式每次只发送 8 种带 ID 的编辑操作未被提及的段落原样保留。四、检索实现recall 同时执行四路检索检索方式作用语义检索向量相似度匹配关键词检索BM25。长查询时只保留文档频率最低的 16 个词用于命中专有名词和错误码图检索沿实体、时序、因果三类边扩展时序检索处理带时间范围的查询把时间窗分桶后逐桶取最相关结果四路结果经过三个阶段处理RRF 融合。k60四路等权只使用排名不使用原始分数。cross-encoder 重排。取融合后前 300 条逐对打分。系数微调。重排结果乘以三个有界系数分别是时效性、时间邻近度和证据数量其中证据数量系数为(10.1·proof)。三项全部取满时总分最多提升 27%。这一阶段有具体的实现约束。官方文档记录过一次配置事故在分数域对某一路结果做乘法加权后1.5 万条记忆规模的库上 recall20 从 0.97 降到 0.40原因是加权改变了候选的入选资格300 个重排名额被单一路径占满。后续修复改为在排名域使用除数。工程结论是不同检索路径的原始分数不可直接比较调整权重应当作用于排名。五、实测数据测试环境hindsight-api 0.4.17PostgreSQL 17pgvector pg_trgm本地嵌入模型 bge-small-en-v1.5384 维重排模型 ms-marco-MiniLM-L-6-v2。一次 retain约 3000 字符文本的落库结果14 个 memory_unitsworld 7 observation 7 90 条 memory_linkstemporal 42 / semantic 35 / entity 10 / caused_by 3 10 个 entities 1 个 document一次 recall 的耗时分布总计 0.93 秒query embedding 48 ms 四路并行检索 319 ms语义 25 条 / BM25 22 条 / 图 3 条 / 时序 0 条 RRF 融合 1 ms cross-encoder 重排 536 ms token 预算过滤 1 ms选中 25 条 / 1215 token / 预算 2000重排占总耗时的 58%。排名第一的结果在 RRF 阶段排第 4经重排后升至第 1。测试中遇到两个问题知识页带 tags 时刷新使用严格全匹配未打标签的记忆全部不可见会生成空页。解决方式是知识页和记忆采用一致的标签策略。中文和英文表述没有发生合并原因是默认嵌入模型的跨语种能力有限。这符合宁可重复不可丢失的合并原则。六、优缺点优点证据链和撤回机制完整记忆可追溯、可审计。评测数据经第三方复现。LongMemEval 达到 SOTA性能数据由 Virginia Tech Sanghani Center 和《华盛顿邮报》独立复现官方 README 中注明其他项目的数据为厂商自报。对 LLM 不可靠的环节设置了确定性约束包括禁止算术推导、引用 ID 校验、增量编辑按 ID 寻址、失败时不写入。接入方式覆盖多种场景包括 SDK、LLM Wrapper、编码 Agent 插件和 MCP。生态覆盖较广支持 25 种以上 LLM provider、60 种以上集成以及 22 种编码 Agent。支持多语言实体保留原文写法提供 Memory Defense 功能可按 bank 扫描密钥和 PII命中后可脱敏或拦截。局限写入侧成本较高。事实提取和 consolidation 都需要调用 LLM实测一次 3000 字符入库消耗约 3-4k token。部署组件较多。完整形态包含 API、worker 和 PostgreSQL 三个进程。默认按 3000 字符零重叠切块跨块的事实可能丢失。零重叠是为了保证 chunk 哈希幂等属于取舍。跨语种合并能力受嵌入模型限制中英文内容不会自动合并。版本迭代快。实测使用的 0.4.17 与当前 0.10.2 之间相差 6 个小版本参数和默认值可能变化。官方文档说明对于 n8n 一类的简单工作流使用 Hindsight 可能过重。七、适用场景适合需要跨会话积累项目知识、沉淀工程经验的场景。对审计和撤回有要求的场景例如工业、EDA、医疗、法务。多租户或多 Agent 共享知识的服务。查询类型多样涉及时序、因果和实体关系的场景。已有应用需要低成本接入记忆能力可以用 LLM Wrapper 在现有客户端外包装一层业务代码基本不用改。不太适合个人编码助手只需要记录上次的工作进度。claude-mem 一类基于 hook 的方案更轻量。需要嵌入 harness 的即时上下文。OpenViking 一类的上下文文件系统更合适。写入成本敏感或要求零 LLM 调用的场景。MemPalace 一类的 verbatim 方案更合适。简单工作流场景。与同类方案的定位区别可以概括为OpenViking 面向分类知识的容器管理Hindsight 面向分层知识的演化和可信度claude-mem 解决的是会话内容不丢失的问题。八、总结Hindsight 的设计重点在于知识随证据演化。为此它引入了 proof_count 计数、对应的排序系数、沿引用链的撤回通道以及在提示词中明确禁止数值推导。从工程角度看它的三个特点可以概括为写入成本较高读取路径稳定错误可以修正。完整代码和文档有更新较快的部分动手前建议以官方文档当前版本为准。相关链接仓库https://github.com/vectorize-io/hindsight官方文档https://hindsight.vectorize.io/快速开始https://hindsight.vectorize.io/developer/api/quickstart实战教程https://hindsight.vectorize.io/guides官方课程https://learn.hindsight.vectorize.ioAPI 参考https://hindsight.vectorize.io/api-reference论文https://arxiv.org/abs/2512.12818实时基准榜https://benchmarks.hindsight.vectorize.io/