2026 年 9 月 28 日的 GitHub 趋势日榜上,vectorize-io/hindsight 排在第三位,但当日新增 4,413★ 是榜上增量最高的一项——比同日第一的 VoiceStudio(+3,274★)和第二的 Paperclip(+3,185★)都高。

仓库元数据(GitHub API 取数时间 2026-09-28 21:33 CST):39,742★、5,284 fork、88 watcher、177 条 open issue、MIT 协议、Python、2025-10-30 建仓、最后一笔 push 2026-09-28 13:28 UTC。最近一次发版 v0.10.1(2026-09-21),往前是 v0.10.0(9/14)、v0.9.2(8/25)、v0.9.1(8/14)、v0.9.0(8/7)——一个半月五个版本。npm 侧最近一周(2026-09-21~2026-09-27)下载:客户端 @vectorize-io/hindsight-client 44,381 次、编码 Agent 包 @vectorize-io/hindsight-coding-agents 11,569 次、一体化包 @vectorize-io/hindsight-all 8,347 次。

它这一周突然往上窜,有两个叠加原因:

  • 9 月 23 日,Hermes 把内置记忆层移出了内核。官方公告的说法是「Nous Research 正在把每一个记忆供应商从 hermes-agent 核心目录移进各维护方自己的仓库,通过插件目录发布,Hindsight 是第一个」,对应的 PR 标题就是「hindsight moves to the plugin catalog」,仓库里原有的 plugins/memory/hindsight/ 目录被删掉。这件事我们下面单独一节讲——因为它直接决定了你想用的时候敲哪条命令。
  • 9 月 21 日发了 v0.10.1,仓库处于活跃维护状态;v0.9.x → v0.10.x 这条线上,官方榜单页的分数也在持续更新。

一句话定位:它不是“给模型外挂一个向量库”

README 的第一句把区别写得很直白:大多数记忆系统只做“回忆对话历史”,Hindsight 要做的是“会学习的 Agent”。

论文(arXiv 2512.12818,2025-12-14)对同行的批评更具体,原文大意是:现在这一代 Agent 记忆把记忆当成一个外挂层——从对话里抽出片段,塞进向量库或图库,再把 top-k 召回塞回提示词。这样做改善了“个性化”和“跨会话带货”,但它把「证据」和「推论」搅在一起、长周期信息组织不起来、而且不支持让 Agent 解释自己的推理过程。

Hindsight 的解法是把记忆当成推理的一等底座,拆成结构化的网络:世界事实、Agent 经历、实体摘要、演变中的信念。

核心功能:四个记忆网络 + 三个操作

四个记忆网络,顶掉“一层向量检索”

  • 世界事实(World facts):关于世界的事实,比如「灶台会烫」。
  • 经历(Experiences):Agent 自己的经历,比如「我摸过灶台,很疼」。
  • 观察(Observations):从大量记忆里合并出来的、带证据背书的信念。
  • 心智模型(Mental models):从观察和事实里学出来的、对所处世界的理解。

写法上,一条记忆进来先被推进「世界事实」或「经历」两条通路之一,再被表达成实体、关系、时间序列的组合,并配稀疏/稠密两种向量表示,供后续召回使用。记忆装在 bank(记忆库)里,一个 bank = 一个用户/一个 Agent/一个项目的一份“大脑”,bank 之间严格隔离、不串味。

三个操作:retain / recall / reflect

操作干什么机制细节
retain写入记忆用 LLM 抽取关键事实、时间、实体、关系,再做归一化(规范实体、时间序列、索引),所以写入慢、要花 LLM 调用
recall检索记忆四路并行:语义(向量相似)、关键词(BM25)、图(实体/时间/因果链)、时间(时间范围过滤);四路结果用 RRF 融合 + 交叉编码器重排,再按 token 上限裁剪
reflect对记忆做推理不止查,是让 Agent 在已有记忆上形成新连接、回答需要“想一下”的问题

reflect 的行为会被 bank 的**性格倾向(disposition traits)**影响,官方给的三个例子是怀疑(skepticism)、字面主义(literalism)、共情(empathy)——同一个 bank、同一个问题,倾向不同,回答不同。

两条容易被忽略但很实用的设计

  • 观察(Observations)有证据链。相关事实在后台被合并成去重后的信念,每条观察保留支撑它的原文引用和一个证明计数;新证据到来时是「精炼」而不是「覆盖」——新信息可以加强、削弱或扩展一条已有信念,而不是悄悄把它替换掉。
  • 心智模型 = 读取不要钱。你可以为一个 bank 预先定义一个常驻问题(比如「这个用户的偏好是什么」),Hindsight 把答案写好、存好,并在后台随记忆增长重写。读它是一次数据库读,不触发检索、不调 LLM——Agent 启动时直接带着一页“已经定论的知识”开工,而不是每个会话重新发现一遍。再往上还有「知识页(knowledge pages)」:把机制藏起来,做成一个 bank 给自己写的活文档,像 wiki 一样分文件夹、可搜索,还能导出成普通 markdown。

安全与语言:两处细节对个人玩家尤其重要

  • Memory Defense:45 条正则模式,扫描每次 retain 的内容,命中密钥、API Key、数据库连接串、已知 PII 格式时,替换成 [REDACTED:github_token] 这类标记后再落库,也可以直接拦下不写。它是按 bank 开启的、默认关闭;而且只影响开启之后的写入,已有记忆不会被追溯清洗——想用就得早点开。
  • 多语言默认保留原样:输入语言被识别并端到端保留,实体保留原生字符——文档里的例子就是「张伟还是张伟,不会被写成 Zhang Wei」。对中文项目,这一条比参数表更实在。

接法:从两行代码到 60+ 集成

  • 最省事:LLM Wrapper。pip install hindsight-litellm 之后把原来的 client 换成 wrap_openai(OpenAI(), bank_id="user-123"),记忆的读写就自动挂在每次调用上;Anthropic SDK 对应 wrap_anthropic()。底层是 LiteLLM,因此同一套写法覆盖 100+ 模型。
  • 要精细控制:Python / Node.js / Go 三套 SDK,加 CLI 和 REST API,显式决定什么时候存、什么时候取。
  • MCP 内置:每个 bank 自带一个 MCP 端点 http://localhost:8888/mcp/{bank_id}/,把 retain / recall / reflect 当成工具暴露出去,任何 MCP 客户端都能接。
  • 集成清单:官方数字是 60+,多数不需要改代码。里面既有编码 Agent(Claude Code、Codex、Cursor、GitHub Copilot、opencode、Cline、Aider、Zed、Continue、Roo Code、OpenHands),也有框架(LangGraph / LangChain、LlamaIndex、CrewAI、Pydantic AI、OpenAI Agents SDK、Google ADK、Agno、Strands、AutoGen、微软 Agent Framework、Vercel AI SDK、Haystack),还有低代码与工具(n8n、Zapier、Dify、Flowise、ChatGPT、Perplexity、Obsidian)。
  • 给编码 Agent 的专用包:npx @vectorize-io/hindsight-coding-agents install all(或 install claude-code 只装一家),覆盖 18 个编码 Agent。它的逻辑是:一个仓库一个 bank,自动从 git 历史和过往会话里吸收内容,没有安装后的“导入”步骤。官方给的理由值得一读——「一个真实修复的大部分都能从代码里推出来,但最后一公里常常卡在代码里根本没有的项目决策上:某条舍入规则、某条重试白名单、某个平局该怎么判。这些决定躺在 git 历史和过去的对话里。」装好之后,这些决定会在 Agent 开始干活的那一刻递到它面前,并维护一组知识页(架构、约定、进行中的事项)。

怎么用起来:三条路,先走 Docker

路径命令骨架适合谁 / 代价
Docker(官方推荐)docker run -it --name hindsight -p 8888:8888 -p 9999:9999 -e HINDSIGHT_API_LLM_API_KEY=... -v hindsight-data:/home/hindsight/.pg0 ghcr.io/vectorize-io/hindsight:latest最快见到东西:API 在 8888、Web UI 在 9999,数据卷落在容器里
裸机(pip)pip install hindsight-api → hindsight-api不想装 Docker;镜像相关依赖自己解决,要求 Python ≥ 3.11
Python 内嵌(免服务)pip install hindsight-all,在代码里 with HindsightServer(llm_provider=..., llm_model=..., llm_api_key=...) as server:脚本/临时验证用;一体化包本身只有 0.01MB 的壳,重量全在它拉起来的依赖(本地 ML 栈 + 内嵌 Postgres)上
Kuberneteshelm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight --set api.llm.provider=openai --set postgresql.enabled=true已经有集群的人
托管(Hindsight Cloud)客户端指向 https://api.hindsight.vectorize.io不想碰基础设施;按 token 计费,详见下一节

三个口径可以先记住:

  • 镜像体积:ghcr.io/vectorize-io/hindsight:latest 是多架构镜像(amd64 + arm64),amd64 侧 22 层、压缩后约 865MB。
  • 模型供应商 25+:HINDSIGHT_API_LLM_PROVIDER 支持托管侧(openai、anthropic、gemini、groq、bedrock、vertexai、minimax、deepseek、atlas、meta…)、全本地(ollama、lmstudio、llamacpp)、任意 OpenAI 兼容端点,以及 litellm 网关。
  • 已有订阅能直接顶掉一部分 API 账单:官方明确写了 openai-codex(ChatGPT Plus/Pro)、claude-code(Claude Pro/Max)、cursor(Cursor)、github-copilot(GitHub Copilot)这四种不需要另外配 API Key。

Hermes 用户这一步:9 月 23 日之后怎么装

这是本周最值得单独拎出来的变化。9 月 25 日官方那篇公告把过程说全了:

  • 老用户什么都不用做。Hermes 会在 hermes update 或下一次启动 Agent 时自动迁移,配置项 memory.hindsight、bank id、~/.hermes/hindsight/config.json、~/.hermes/.env 里的 Key 全部不动,三个工具名也不变:hindsight_retain、hindsight_recall、hindsight_reflect。迁移后插件落在 ~/.hermes/plugins/hindsight/,config.yaml 里补上 plugins.enabled: [hindsight]。
  • 新用户两条命令:hermes plugins install hindsight,然后 hermes memory setup(在向导里选 hindsight)。
  • 三个真会踩的坑:①hermes plugins enable 不会激活记忆供应商——Hermes 把供应商当 kind: exclusive 处理,真正生效的是 config.yaml 里的 memory.provider: hindsight,这一步由 hermes memory setup 写入;②hermes update 不会更新插件,得用 hermes plugins update hindsight;③更新过程是交互式的,会问是否准备插件的 Python 依赖,无人值守的 hermes update 会卡在这个提问上。
  • 老插件已废弃:早先那个装进 Hermes venv 的 hindsight-hermes pip 插件在当前版本上会报 {"error": "Timeout context manager should be used inside a task"},官方指向「迁移到原生 Hermes 记忆」的指南,并保证 bank 不变。

我们自己在本机核对了 Hermes 的插件目录条目(取数时间与上文相同):hindsight 在策展目录里是 community 层级,维护方 vectorize-io,固定 commit 176f8c2d…,要求 hermes >= 0.21.4,插件代码在被管理仓库的子目录 hindsight-integrations/hermes 下。目录条目上明确写了一条例外:内嵌本地模式在当前 pin 版本上不被支持——它仍会去调用已退役的 hindsight-all 懒安装路径;云端模式和本地外部模式可用。也就是说,如果你打算用「本地外部」这条路(自己起一个 Hindsight 服务,让 Hermes 指过去),这是可行且被支持的;想完全免服务地内嵌,Hermes 侧目前不是官方支持的组合。

账怎么算:自托管免费,但 LLM 调用费在你这边

官方定价页把两条路的差别写得没有歧义:

自托管Hindsight Cloud
费用免费,MIT 协议,无用量限制、无遥测按用量计费,无固定月费、无按席位收费
基础设施你自己的 Docker / K8s / 机器托管、自动扩缩、每日备份、看板
支持社区(GitHub)12×5 邮件,99.9% SLA(企业版最高 99.95%、30 分钟响应)
起步一条 Docker 命令送初始额度,可以先用再付

Cloud 的单价是公开的(这是少见的透明,直接抄给你):

  • Retain(写入记忆)$10.00 / 百万 token
  • Recall(检索记忆)$0.75 / 百万 token
  • Reflect(综合推理)$0.05 / 次调用
  • Iris Extract(结构化抽取)$7.50 / 百万 token
  • 心智模型检索 $0.25 / 百万 token;心智模型刷新 $0.05 / 次调用
  • 存储 $0.25 / 百万 token / 月,而且前 30 天免费,只对超过 30 天的部分计费,记忆不会被删

自托管的“免费”只免掉了这一层。真正的开销是你自己出的 LLM 账单——因为 retain 每批要花 500ms~2000ms 做一次 LLM 事实抽取,写入量大的话,这块是主要成本项。官方性能页给的三个数字可以直接当预算依据:

操作典型延迟瓶颈在哪
Recall100–600ms重排器(跑在 CPU 上时)
Reflect800–3000msLLM 生成
Retain500–2000ms / 批LLM 事实抽取

设计取向也写明了:整个系统是为“读快”而不是“写快”优化的——embedding 在写入时就算好并建索引(HNSW),事实抽取也在写入时完成,所以 recall 路径上不干重活。存储底座是 PostgreSQL + pgvector,全文检索走内置 tsvector + GIN 索引,图查询用递归 CTE,文档用 JSONB——官方特意强调这样能「减少系统依赖」,企业版可换 Oracle AI Database 23ai。换句话说,自托管的最小代价不是“一条命令”,而是你得有一个 Postgres 在跑(内嵌 pg0 只是把这件事打包了)。

成绩单怎么读:论文数字、榜单数字、厂商自报要分开

这块很容易被当成营销图,所以我们把三层分开摆:

第一层,论文口径(2025-12-14,arXiv 2512.12818):用开源 20B 模型,相对“同底座的全上下文基线”,整体准确率从 39% 提到 83.6%,并超过全上下文的 GPT-4o;继续放大底座后,LongMemEval 91.4%,LoCoMo 89.61%(对比此前最强开源系统的 75.78%)。

第二层,官方榜单口径(2026 年 1 月起持续更新,benchmarks.hindsight.vectorize.io):LongMemEval S 94.6%、LoComo 10 92%、PersonaMem 32K 86.6%、BEAM 100K 75%、BEAM 1M 73.9%、LifeBench EN 71.5%、BEAM 500K 71.1%、BEAM 10M 64.1%。榜单上还有选型表:retain 对比了 36 个模型(当时第一是 GPT-5.6 Luna 低推理档)、reflect 21 个(第一 openai/gpt-oss-120b)、重排 10 个(第一 MiniLM-L6)、embedding 7 个(第一 BGE Small EN v1.5)。

第三层,独立复现:README 说基准成绩已被弗吉尼亚理工 Sanghani 人工智能与数据分析中心、以及《华盛顿邮报》的研究合作者独立复现,并点明「其他厂商的分数是自报的」——这句话本身就是本文愿意引用它的原因。另外官方说法是已在财富 500 强企业内部生产使用,但没有给出可核对的客户名单,这一条只当背景看。

三个口径的差别不是小数点问题:论文用的是当时可用的模型和基线,榜单在持续更新、口径是「Agent Memory Benchmark(AMB)」这一套;而 91.4% 与 94.6% 之间的差距,来自底座、口径和时间的共同变化。跨口径直接和别人家的数字对比,是没有意义的。

和同类比:它和国产的 TencentDB Agent Memory、以及 Hermes 自带记忆差在哪

HindsightTencentDB Agent Memory(我们 9/14 写过)Hermes 自带记忆
分层方式四个记忆网络:世界事实 / 经历 / 观察 / 信念L0 对话 / L1 事实 / L2 场景 / L3 画像四层 + 四类资产会话内记忆 + 你手写的持久笔记
检索语义 + BM25 + 图 + 时间四路并行,RRF 融合 + 交叉编码器重排向量 + BM25 混合取决于配置,以文件/短上下文为主
底座PostgreSQL + pgvector(自托管),内嵌 pg0 或 Oracle本地优先、零外部 API 依赖无外部服务
成本模型自托管免费 + 你的 LLM 账单;云端按 token 明码标价本地跑,不花 API 钱免费
顺手程度60+ 集成、MCP 内置、18 个编码 Agent 一个包一条命令起三件套,8 家客户端零安装

一句话区分:TencentDB 那套是“把记忆做成资产和分层”(本地优先、不花 API 钱,代价是要自己维护一套服务);Hindsight 是“把记忆做成推理底座”(会做观察与信念合并、能解释证据,代价是写入要吃 LLM 调用)。 如果你的痛点只是“换个会话就失忆”,自带记忆或腾讯那套更省;如果痛点是「同一个项目里,三个月前的那个决定今天还能不能还原出来、并且说清依据」,那是 Hindsight 这一格。

我的判断:谁该上,谁再等等,谁别碰

该上的三类人:

  1. 手上同时跑 Claude Code / Codex / Hermes 的人。它一个包把 18 个编码 Agent 的记忆统一到一个 bank 上,而且会自动吃 git 历史和过去会话——这是“多工具、多仓库、同一项目”的典型场景。
  2. 已经在付 Claude Pro / ChatGPT Plus / Cursor / Copilot 订阅的人。这四种订阅可以直接当模型后端,不用额外配 API Key,试错成本基本压到零。
  3. 愿意为“可解释的记忆”付成本的小团队。观察带原文引用 + 证明计数、信念是精炼不是覆盖,这两条在需要复盘“为什么当时这么定”的时候价值很直接。

再等等的:

  • 只跑一台 1.6G 内存小机的人。官方推荐路径是一条 Docker 命令,而镜像是压缩后约 865MB 的多层镜像,底座还要一个 Postgres;内嵌模式那 0.01MB 的壳下面拉的是本地 ML 栈和数据库。这不是“装不上”,而是它和你机器上已有的服务抢内存的性价比不高——真想在自己机器上跑,更好的形态是把 Hindsight 放在有资源的机器/内网,让 Agent 通过 API 或 MCP 指过去。
  • 只是单轮问答、或用不到跨会话的人。多一层记忆就是多一层 LLM 调用和一份运维对象,收益为零。
  • 已经在用 Hermes 且只想“有记忆”的人。先想清楚你要的是“记住”,还是“学会”;要的只是前者,别上。

别碰的:

  • 拿它当文档/知识库检索用的人。它的定位是 Agent 记忆,不是 RAG 平台(官方自己也把 RAG 平台单列)。文档检索塞进去,你会得到一堆被合并过的“信念”,而不是可溯源的分块。
  • 对隐私零容忍却开云的人。自托管才是 MIT + 无遥测的那条路;云是另一套信任模型。反过来,如果你在意密钥别被记住,Memory Defense 要提前开——它不追溯。
  • 指望零成本的人。自托管免费的是软件,不是 LLM。

最后一句收口:记忆不是把上下文变长,而是把“过去的决定”变成今天能直接读的一页——这个项目值不值得用,取决于你手上有没有那种“半年后还要翻回去找依据”的活。

主要来源:GitHub 仓库与 README;官方文档 Installation / Storage / Performance / Memory Defense / 编码 Agent 集成页;benchmarks.hindsight.vectorize.io 与 agentmemorybenchmark.ai;arXiv 2512.12818;vectorize.io/pricing;Hindsight 官方博客 2026-09-25「moves to the plugin catalog」;Hermes 插件目录本机条目(2026-09-28 21:33 CST 取数);GitHub API / npm registry / PyPI JSON 元数据。

顺带一提:想把这层记忆服务自己托管的话,先看看真机数字——1.6GB 服务器跑多服务实测里每个服务占多少内存都记了账。

本文由拾光札记编辑部整理,勘误请联系我们。