---
url: /hindsight/introduction.md
description: >-
  Hindsight 是 Vectorize 开源的 AI Agent 长期记忆系统（MIT 协议，最新 v0.10.0），用 retain / recall
  / reflect 三个原语让 Agent 跨会话记住、巩固并学会。核心是 TEMPR 四路并行检索（语义 + BM25 关键词 + 实体图谱 + 时间）经
  RRF 融合与 cross-encoder 重排，LongMemEval-S 94.6%、LoComo-10 92%、BEAM 10M 64.1%
  全部第一；支持 Docker 一键起、pip 嵌入式、Helm 上 K8s，60+ 集成覆盖 Claude
  Code、Cursor、LangChain、Dify、n8n、MCP。
---

# 认识 Hindsight：Agent 每次开新会话就失忆？这个 27.8K Star 的开源记忆系统把 LongMemEval 打到 94.6%

先讲一件我这周遇到的事，挺丢人的。

我给自己搭了个写代码的小 Agent，上周跟它掰扯了半个小时，最后定了三条规矩：项目里不许用 `Any`、日志统一走 `structlog`、测试必须能并行跑。它当时答应得好好的。

这周新开一个会话，我随口问了一句"测试怎么跑"，它给我回了一段用 `unittest`、还带 `time.sleep(3)` 的代码。

我盯着屏幕愣了两秒——**它不是变笨了，它是真的忘了。**

一个字都不记得。上周那半小时的对话，对它来说从来没发生过。

这就是今天几乎所有 AI Agent 的默认状态：\*\*每次会话都是一次彻底的失忆。\*\*你以为你在"训练"它，其实你只是在跟一个每天早上都会重置的人重新自我介绍。

然后我看到了一组让我更难受的数字：\*\*Mem0 的开源版在 LongMemEval 这个长期记忆基准上只有 49.0%。\*\*也就是说，一半的问题它记错了或者压根没记住。

而 2026 年 9 月 25 日这天，GitHub Trending 榜第一的项目叫 **Hindsight**——单日涨了 **1668 个 Star**，总 Star 数约 **27.8K**。它在这个基准上写的是 **94.6%**。

差了 45 个点。这已经不是"优化"了，这是**两条不同的技术路线**。

## 什么是 Hindsight

**Hindsight 是 Vectorize（vectorize-io）开源的一套 AI Agent 长期记忆系统，MIT 协议，最新正式版 v0.10.0（2026 年 9 月 14 日发布，PyPI 上 hindsight-api 已到 0.10.1 / 9 月 22 日）。它不是一个向量数据库，也不是 RAG 框架的换皮，而是一个自带"记忆分层 + 记忆巩固"的服务：你用 retain() 存、用 recall() 查、用 reflect() 让它带着立场回答。底层是 PostgreSQL + 向量扩展（pgvector / pgvectorscale / vchord / scann），所有数据都在你自己手里，可完全自托管。**

先把最容易搞混的一件事说清楚：**Hindsight 不是 RAG。**

| | RAG | Hindsight |
|---|---|---|
| 检索策略 | 只有语义相似度 | 语义 + 关键词 + 图谱 + 时间，四路并行 |
| 多跳推理 | 受限于召回的片段 | 沿实体关系图遍历 |
| 时间查询 | 关键词碰运气（"春天"） | 解析日期、按范围过滤 |
| 实体理解 | 无 | 实体消歧、共现追踪 |
| 知识沉淀 | 无状态 | 观察 → 心智模型，会演化 |
| 立场 | 无 | skepticism / literalism / empathy 三档可调 |

> RAG 回答的是"哪段文档像这个问题"。
> 记忆回答的是"关于这个人 / 这件事，我们目前知道什么，以及我们是怎么知道的"。
> 这两件事在企业里根本不是同一个需求，但过去两年我们一直在拿前者硬凑后者。

它的全部 API 只有三个动词，我第一次看文档时觉得这也太少了，看完才明白这是刻意的设计：

* **`retain()`** —— 喂进去一段对话 / 文档 / 转录，它抽取事实、识别实体、在时间轴上挂好；
* **`recall()`** —— 四路检索并行跑，融合重排后在 token 预算内返回最相关的记忆；
* **`reflect()`** —— 拿召回的记忆做一次带立场的推理，生成答案。

> 这三个词对应的是人类记忆的三个动作：记下来、想起来、琢磨一下。
> 大部分"记忆方案"只做了前两个，然后管第三个叫"让模型自己总结"。

## 它有什么特点

### 第一，TEMPR 四路并行检索，是它和所有对手拉开差距的地方

一次 `recall("Alice 去年三月做了什么")` 进去，**没有任何一个环节会先猜这个问题适合哪种检索**，四条路同时跑：

| 检索臂 | 用什么 | 擅长什么 |
|---|---|---|
| Semantic | 向量 | 概念相似、改写过的说法 |
| Keyword | BM25 | 人名、术语、精确匹配 |
| Graph | 实体图谱 | 关联实体、间接关系 |
| Temporal | 日期索引 | "去年春天"、"六月"、时间区间 |

四条路各自排一个序，然后 **RRF 融合**（`Σ 1/(60 + rank)`）合成一个列表，再上一道 **cross-encoder 重排**，最后按**新鲜度、时间、证据强度**加权，砍进你给的 `max_tokens` 预算里。

为什么这件事重要？因为 Mem0 和 Zep 都**只跑一到两条路**（Mem0 主力是语义、图谱要上 Pro 版；Zep 是图谱 + 语义增强）。碰到"时间 + 实体 + 语义"混在一起的问题，它们只能赌一条路，而 Hindsight 四条全跑。

官方给的那个例子我特别喜欢：

> 存进去的事实是：Alice 是 Project Atlas 的技术负责人 → Project Atlas 用 Kubernetes → Kubernetes 集群周二宕机了。
> 问："Alice 受最近故障影响了吗？"
> RAG 只会召回关于 Alice 的那几条（"故障"和 Alice 在语义上不相似）。
> Hindsight 沿着 Alice → Atlas → Kubernetes → 宕机 这条实体链走一遍，然后回答"是"。

### 第二，记忆会"巩固"，不是堆碎片

这是我认为 Hindsight 最不像竞品的一点。它的记忆分四层：

| 类型 | 存什么 | 例子 |
|---|---|---|
| **World Fact** | 客观事实 | "Alice 在 Google 工作" |
| **Experience Fact** | 这个记忆库自己的行为和交互 | "我向 Bob 推荐了 Python" |
| **Observation** | 从多条事实**自动巩固**出来的认知 | "用户曾是 React 爱好者，现在已经转向 Vue"（保留了演变过程） |
| **Mental Model** | 人工整理的常用问题摘要 | "团队沟通最佳实践" |

关键在 **Observation（观察）**这一层：相关事实会自动合并成一条持久的认知，而不是无限堆积重复项。每条观察都带着**证据追踪**——引用它来源的原始记忆原文，外加一个 proof count（支持它的证据条数）。新证据来了不是覆盖，是**更新，且保留历史**。

`reflect()` 的时候查源有优先级：**Mental Models → Observations → Raw Facts**。

> "用户曾是 React 爱好者，现在已经转向 Vue"——这句话里藏着一条时间线。
> 一个只会堆事实的系统，会同时告诉你"他喜欢 React"和"他喜欢 Vue"，然后让你自己去猜哪个是新的。
> 这就是"记住"和"学会"的区别。

### 第三，记忆库可以有立场：Mission / Directives / Disposition

每个 bank（记忆库）可以配三样东西：

| 配置 | 作用 | 例子 |
|---|---|---|
| **Mission** | 自然语言描述这个库是谁、关注什么 | "我是专注机器学习的研究助理，偏好简单方案而非最新方案" |
| **Directives** | 硬规则，永远不能违反 | "绝不推荐具体股票"、"必须引用来源" |
| **Disposition** | 软特质，1-5 档影响推理风格 | 怀疑度（skepticism）、字面度（literalism）、共情度（empathy） |

\*\*Directives 是硬约束，Disposition 是软风格。\*\*这两条分开，是工程上很聪明的一刀——合规规则不能商量，语气风格可以调。

注意它**只影响 `reflect()`，不影响 `recall()`**。检索结果保持客观，解读阶段才带立场。

### 第四，v0.10.0 这一版加的东西都很实在

9 月 14 日发的 0.10.0，我挑几条真正影响使用的：

* **图片和文件成了 retain 的一等公民**：`content` 现在吃一个有序的 text / image / file 块列表，截图在两段文字中间，就按"中间那张图"来读。**证据追踪细化到每条事实**，散文里写的事实不会把旁边的截图认领成自己的证据。recall 回来的事实也带着支撑它的附件。
* **请求路径快了 3.2 倍**：两个 HTTP 中间件改成纯 ASGI，embedding 批处理并发，token 计数更便宜。
* **能在花钱之前先看到 prompt**：retain / consolidate / reflect 都加了 preview 端点，控制面板里还有 retain 的 prompt 测试器。这条对调过 prompt 的人来说是救命的。
* **recall 支持模糊匹配标签 + 开放词表的多值标签**：不用再预先枚举分类了，让库自己从内容里长出来。
* **0.10.0 里 reflect 不再对空缺期编数字**：以前问一个库里没有数据的时期，它会从邻近期外推一个具体数字当结论。现在它会说"这个值没有记录"，同时保留定性结论。

最后这条我要单独夸一句。**一个记忆系统愿意承认"我不知道"，比它多答对 5% 重要得多。**

### 第五，基准成绩，以及我必须泼的冷水

官方实时看板（benchmarks.hindsight.vectorize.io）上的数字，全部自称第一：

| 数据集 | Hindsight |
|---|---|
| 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%** |

对比着看才有意义（数据来自各厂商公开页面，口径不完全一致）：

| 系统 | LongMemEval | LoComo |
|---|---|---|
| Hindsight | 94.6% | 92% |
| Mem0（闭源平台） | 94.4% | 92.5% |
| Mem0（开源版） | 49.0% | 57.7% |
| Zep | 63.8% ~ 90.2% | 71.2% ~ 94.7% |
| Letta | — | 74.0% |

好，冷水来了，而且不止一盆：

\*\*第一，这个看板上只有 Hindsight 自己的分数。\*\*没有竞品、没有延迟、没有成本、没有日期。官方 README 说"实时更新，含每模型的准确率、延迟和成本"，但当前页面只兑现了准确率这一项。Agent Memory Benchmark 本身就是 Vectorize 的项目。

\*\*第二，数字对不上。\*\*仓库 benchmark 目录里写的是 LongMemEval-S **91.4%**、LoCoMo overall **89.61%**，实时看板上是 94.6% / 92%。涨了，但没说为什么涨。

\*\*第三，有人质疑这个记忆层反而拖累了模型。\*\*Honcho 在 2025 年 12 月的博客里点名说：Gemini 3 Pro **裸跑同一份题目就有 92.0%**，比 Hindsight 当时公布的 91.4% 还高。言下之意是，加记忆层反而没跑过不加。这个质疑附了可复现代码。

\*\*第四，也是最要命的一条——成本。\*\*Mem0 官方对比页的数据：

| | LongMemEval | 每次检索 token |
|---|---|---|
| Mem0 | 94.4% | **~7K** |
| Hindsight | 94.6% | **~27K** |

\*\*准确率只高 0.2 个点，token 花了近 4 倍。\*\*在 BEAM 10M 上是 73.9% vs 64.1%（Hindsight 明显更强），但代价是 43.6K vs 6.7K tokens。

> 我的看法很直接：**Hindsight 是在用钱换召回率。**
> 如果你每次调用都要付 27K token，那"记忆"这件事的账就得重新算——一个每天 10 万次调用的应用，光记忆检索就是 27 亿 token。
> 但反过来，如果你的场景是"宁可多花点也要答对"（医疗、法务、金融风控），这 0.2 个点可能比你省下的钱值钱得多。

最后补一句公道话：官方说这些结果由 **Virginia Tech Sanghani Center** 和\*\*《华盛顿邮报》\*\*的研究合作者独立复现过，基础设施只是本地 MacBook + PostgreSQL。这在"所有分数都是厂商自报"的行业里，已经算有诚意了。

## 用在哪儿

### 语音客服 / 呼叫中心：这是我觉得最刚需的场景

Hindsight 官方集成了 **Vapi** 和 **Pipecat** 两个语音 AI 平台，模式一模一样：**通话开始时召回这个来电人的上下文，通话结束时把整段转录 retain 进去。**

价值在哪？一个老客户第三次打进来，Agent 已经知道他上次报的是什么问题、上次的处理方案是什么、他对什么方案表达过不满。这不需要客户重复三遍。

这个场景下 token 成本反而不是问题——**一通电话才几十轮对话，但每轮的价值极高。**

### 编码 Agent：这可能是它涨 Star 最快的原因

官方有个专门包：`npx @vectorize-io/hindsight-coding-agents install all`，一条命令给 **Claude Code、Codex CLI、Cursor CLI、GitHub Copilot CLI、opencode、Kilo、Cline、Antigravity、Devin、pi、Prime Agent、Grok Build、DeepSeek Harness** 全部装上长期记忆。

它干的事是：**按 git 仓库自动建一个 bank，从 git 历史和过往会话里自动摄取，Agent 开始干活前把上下文注入进去**，再配上架构、约定、在途工作的知识页。摄取是自动的，没有额外命令。

回想我开头那个"它忘了不许用 `Any`"的故事——这个包就是专门治这个的。

### 企业助手 / 工作流：Directives 是这里的关键

通过 **Dify、n8n、Zapier、Flowise、LangChain / LangGraph、LlamaIndex、CrewAI、Pydantic AI、OpenAI Agents SDK、Google ADK、Microsoft Agent Framework** 等 60+ 集成接入。

**Directives（硬规则）在这个场景里是刚需**——"绝不推荐具体股票"、"必须引用来源"、"涉及金额必须转人工"。这些不是 prompt 里的软建议，是写在记忆库配置里、每次 reflect 都会生效的约束。

官方还专门做了一个 **Business Executive bank 模板**，以及和 TealTiger 合作的"治理感知记忆"——重要的拒绝决策持久保存以便合规审计，常规的批准自然衰减。这个思路我很喜欢：**不是所有记忆都该平等地活下去。**

### 还有两个挺有意思的

**Obsidian 集成**——把你的笔记库同步进 Hindsight，然后跟一个 grounded 在你自己笔记上的 Agent 聊天，每条答案都标注它引用的那条笔记。笔记库始终是唯一事实来源。

**ChatGPT 和 Perplexity 通过 OAuth 保护的 MCP 连接器接入**。也就是说你不必换工具，让商业化产品的记忆落在你自己托管的库里。

### 官方口径的客户

Vectorize 说 Hindsight **已在 Fortune 500 企业的生产环境中使用**，也在被一批 AI 创业公司使用。具体名字没公开——这在 B2B 开源里很常见，但也意味着你没法直接验证。请把它当成"厂商声明"而不是"已证实的案例"。

## 初体验

**最快的一条路，Docker 一条命令（API + 控制面板全在里面）：**

```bash
export OPENAI_API_KEY=sk-xxx

docker run -it --pull always --name hindsight --restart unless-stopped --shm-size=1g \
  -p 8888:8888 -p 9999:9999 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -v hindsight-data:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest
```

* API 服务：`http://localhost:8888`（文档在 `/docs`）
* 控制面板（Web UI）：`http://localhost:9999`
* MCP 端点：`http://localhost:8888/mcp/{bank_id}/`

**不想装 Docker 就走 pip：**

```bash
pip install hindsight-api
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
hindsight-api          # 默认 8888，内置 pg0 嵌入式 PostgreSQL，数据在 ~/.hindsight/data/
```

**然后四行 Python，跑通整个闭环：**

```bash
pip install hindsight-client
```

```python
from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

client.retain(bank_id="my-bank", content="Alice 三月加入 Google，她很喜欢研究团队")
print(client.recall(bank_id="my-bank", query="Alice 在哪工作？").results)
print(client.reflect(bank_id="my-bank", query="介绍一下 Alice").text)
```

**真正的"两行代码"是这个——给已有 Agent 加记忆，业务代码一行不用改：**

```bash
pip install hindsight-litellm
```

```python
from openai import OpenAI
from hindsight_litellm import wrap_openai

client = wrap_openai(
    OpenAI(),
    bank_id="user-123",
    hindsight_api_url="http://localhost:8888",   # 不填则走 Hindsight Cloud
)

# 后面该怎么调还怎么调，调用前自动 recall、调用后自动 retain
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "你知道我的哪些偏好？"}],
)
```

`wrap_anthropic()` 对 Anthropic SDK 做同样的事，底层是 LiteLLM，所以 **100+ 模型都能覆盖**。每次调用还能用 `hindsight_*` 参数单独覆盖 bank、检索预算、事实类型，甚至可以改成走 reflect 而不是 recall。

**想连外部服务都不起的，用嵌入式模式：**

```bash
pip install hindsight-all
```

```python
import os
from hindsight import HindsightServer, HindsightClient

with HindsightServer(llm_provider="openai", llm_model="gpt-5-mini",
                     llm_api_key=os.environ["OPENAI_API_KEY"]) as server:
    client = HindsightClient(base_url=server.url)
    client.retain(bank_id="my-bank", content="Alice 在 Google 工作")
    print(client.recall(bank_id="my-bank", query="Alice 在哪工作？"))
```

**给编码 Agent 装记忆：**

```bash
npx @vectorize-io/hindsight-coding-agents install all       # 所有检测到的 Agent
npx @vectorize-io/hindsight-coding-agents install claude-code  # 或只装一个
```

### 六个坑，我提前替你踩一遍

\*\*一，必须有 LLM。这不是纯向量库。\*\*retain 的抽取和 reflect 的推理都要调模型，没配 API key 服务起不来，或者起来也是个空壳。官方推荐 **Groq + `gpt-oss-20b`**，便宜又快。支持的 provider 有 openai / anthropic / gemini / groq / ollama / lmstudio / github-copilot / meta / deepseek。

\*\*二，Docker 镜像比你想的大得多。\*\*Full 版 AMD64 **约 9 GB**（ARM64 约 3.7 GB），因为它把 BGE embedding 模型和 MiniLM cross-encoder 都打包进去了。想要小的用 `slim` 标签（约 500 MB），代价是 embedding 和 rerank 都得走外部服务。内存同理：Full 最低 1.5 GB，Slim 512 MB 起。

\*\*三，pg0 嵌入式数据库只适合开发。\*\*官方明确写了 not recommended for production。上生产请用外部 PostgreSQL 14+，装 pgvector（或 pgvectorscale / vchord / scann）。Supabase、Neon、Azure、AlloyDB、RDS、Cloud SQL 都行。

\*\*四，Docker 跑非 root（UID 1000），bind mount 会踩权限坑。\*\*用 named volume 最省事；非要挂宿主机目录，先 `sudo chown -R 1000:1000`。**别用 `--user` 换 UID**，镜像里只定义了 hindsight 这个用户，换别的会直接崩在 `getpwuid()`。

\*\*五，国内网络有官方解法。\*\*文档里专门写了 China Network Notes：设 `HF_ENDPOINT=https://hf-mirror.com`，provider 用 `deepseek`（DeepSeek 没有 embedding 端点，所以 embedding 走 `local` + `BAAI/bge-small-en-v1.5`，reranker 用 `flashrank`）。这段配置能省你两小时。

\*\*六，Intel Mac 别装 `hindsight-all`。\*\*完整包里的本地模型没有 Intel Mac 的 wheel，pip 会静默回退到一个几个月前的旧版本。请装 `hindsight-all-slim` 或 `hindsight-api-slim`。

再补一条小的：\*\*PyPI 页面上 hindsight-api 的 license 字段写的是 Apache 2.0，但仓库 LICENSE 和 SPDX 表达式都是 MIT。\*\*真要走合规流程，以仓库里的 LICENSE 文件为准。

## 进阶

如果这篇文章你只记住一件事，我希望是这个判断：

**过去两年我们一直在用"更长的上下文窗口"冒充"记忆"，而这两件事根本不是一回事。**

上下文窗口是**工作台**，记忆是**档案柜**。工作台再大也装不下跨月跨年的交互史，成本随长度线性膨胀，而且窗口一清空，一切归零。我那个 Agent 忘了"不许用 `Any`"，不是因为它上下文不够长，是因为**它压根没有"上周"这个概念**。

Hindsight 真正的贡献不是 94.6% 这个分数，而是它把"记忆"这件事拆成了可以工程化的四层：原始事实 → 巩固后的观察 → 心智模型 → 带立场的解读。**它承认了记忆是需要加工的，不是存下来就完事。**

冷水照例要泼，这次泼三盆：

\*\*第一，27K token 一次召回，这个成本你必须自己算清楚。\*\*如果你的应用是高频、低价值的调用（比如每天十万次的简单问答），Hindsight 大概率不划算，Mem0 那 ~7K 的方案更合适。如果你的应用是低频高价值（医疗问诊、法务检索、投研），那 0.2 个准确率的点值得你掏钱。**别看着 94.6% 就冲。**

**第二，所有基准数字都请当成"厂商自报"。**看板上只有它自己、README 和看板对不上、Honcho 质疑裸跑更强——这三件事叠在一起，意味着**你必须在自己的数据上跑一遍**。好消息是它开源、可自托管、有现成的 benchmark 仓库，跑一遍的成本不高。

\*\*第三，它不是一个可以扔进生产就不管的组件。\*\*数据全落在你的 PostgreSQL 里，备份、访问控制、合规审计全是你自己的活。官方自己在文档里把"生产部署指南"单独列了一节——这既是好事，也是一个提醒。

我的建议很具体：\*\*先别急着接 Agent 框架。用 Docker 起一个，拿你真实的一周工作聊天记录 retain 进去，然后只问三个问题——"上周我们定了什么"、"这个项目的约定是什么"、"我讨厌什么做法"。\*\*recall 回来的东西准不准，你一眼就知道。这三句话的召回质量，比任何基准分数都能说明它对你有没有用。

再往深一层，我建议你去读它的 **RAG vs Memory** 那页文档和官方的 **Cross-Encoder Reranking** 那篇博客。看清楚两件事：**为什么"四路并行 + RRF 融合 + cross-encoder 重排"这套组合拳在混合查询上碾压单路检索**，以及**为什么观察巩固必须保留历史而不是覆盖最新**——这两个结论对所有做记忆系统的代码都成立，不管你最后用不用 Hindsight。

至于"Agent 记忆"会不会像"向量数据库"一样变成一个独立的基础设施品类（Mem0、Zep、Letta、Hindsight、EverMind 在同一年里扎堆出现，本身就说明有人押注），我的看法是：\*\*已经成了。\*\*但它还没收敛——现在这个阶段，各家分数打架、口径不一，选型时请务必带上自己的数据和自己的账单。

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。