ghcr.io/vectorize-io/hindsight-api:0.4.14

什么是 Hindsight？

Hindsight™ 是一个代理记忆系统，旨在创建能够随时间学习的更智能代理。大多数代理记忆系统专注于回忆对话历史，而 Hindsight 则专注于让代理学习，而非仅仅记忆。

它消除了 RAG 和知识图谱等替代技术的缺点，并在长期记忆任务上提供最先进的性能。

记忆性能与准确性

根据基准测试性能，Hindsight 是迄今为止测试过的最准确的代理记忆系统。它在 LongMemEval 基准测试中取得了最先进的性能，该基准广泛用于评估各种对话式 AI 场景下的记忆系统性能。截至 2026 年 1 月，Hindsight 和其他代理记忆解决方案的当前报告性能如下：

Hindsight 的基准性能数据已由弗吉尼亚理工大学桑哈尼人工智能与数据分析中心和《华盛顿邮报》的研究合作者独立复现。其他分数由软件供应商自行报告。

Hindsight 已在财富 500 强企业的生产环境中使用，并被越来越多的 AI 初创公司采用。

将 Hindsight 添加到您的 AI 代理中

将 Hindsight 与现有代理结合使用的最简单方法是通过 LLM Wrapper。您只需 2 行代码即可为代理添加记忆功能。这将用 Hindsight 包装器替换您当前的 LLM 客户端。之后，在进行 LLM 调用时，记忆将自动存储和检索。

如果您需要更精确地控制代理存储和回忆记忆的方式与时机，还可以通过 SDK 或直接通过 HTTP 集成简单的 API。

---

🤖 正在使用编码代理？ 安装 Hindsight 文档技能，以便在编码时即时访问文档：

> npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
>

适用于 Claude Code、Cursor 和其他 AI 编码助手。

---

快速开始

Docker（推荐）

export OPENAI_API_KEY=sk-xxx

docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest

API: http://localhost:8888 UI: http://localhost:9999

您可以通过设置 HINDSIGHT_API_LLM_PROVIDER 修改 LLM 提供商。有效选项包括 openai、anthropic、gemini、groq、ollama、lmstudio 和 minimax。文档提供了有关支持模型的更多详细信息。

Docker（外部 PostgreSQL）

export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up

Oracle AI Database 也支持企业部署，具有完整的功能对等性。有关详细信息，请参阅存储文档。

API: http://localhost:8888 UI: http://localhost:9999

客户端

pip install hindsight-client -U
# 或
npm install @vectorize-io/hindsight-client

Python

from hindsight_client import Hindsight

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

# Retain: 存储信息
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall: 搜索记忆
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: 生成情境感知响应
client.reflect(bank_id="my-bank", query="Tell me about Alice")

Node.js / TypeScript

npm install @vectorize-io/hindsight-client

const { HindsightClient } = require('@vectorize-io/hindsight-client');

const main = async () => {
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });

await client.retain('my-bank', 'Alice loves hiking in Yosemite');

const results = await client.recall('my-bank', 'What does Alice like?');
console.log(results);
}

main();

Python 嵌入式（无需服务器）

pip install hindsight-all -U

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 works at Google")
results = client.recall(bank_id="my-bank", query="Where does Alice work?")

---

使用场景

Hindsight 旨在支持对话式 AI 代理以及旨在自主执行任务的代理。Hindsight 的理想使用场景是需要融合以下功能的代理：例如 AI 员工，他们需要处理开放式任务、根据用户反馈改变行为，并学习执行复杂任务以实现接近人类水平的工作自动化。Hindsight 可用于简单的 AI 工作流（如使用 n8n 和其他类似工具构建的工作流），但对此类应用可能过于复杂。

每用户记忆和聊天历史

Hindsight 最简单的使用场景之一是通过存储和回忆与单个用户相关的记忆，实现 AI 聊天机器人和其他对话代理的个性化。

此场景的需求通常如下：

在 Hindsight 中满足这些需求非常简单。当使用 retain 操作将新的用户输入和工具调用摄入 Hindsight 时，可以使用自定义元数据丰富新记忆。元数据提供了一种便捷的方式来隔离需要限制给特定用户的记忆。一旦这些记忆被输入 retain 操作，在检索相关记忆时，任何创建的原始记忆和心智模型都可以被过滤。

---

架构与操作

大多数代理记忆实现依赖于基本的向量搜索，有时也使用知识图谱。Hindsight 使用仿生数据结构来组织代理记忆，其方式更接近人类记忆的工作原理：

• World（世界）：关于世界的事实（“炉子会变热”）
• Experiences（经验）：代理自身的经历（“我碰了炉子，真的很烫”）
• Mental Models（心智模型）：通过反思原始记忆和经验形成的对代理世界的习得理解。

Hindsight 中的记忆存储在“banks”（即记忆库）中。当记忆添加到 Hindsight 时，它们会被推入世界事实或经验记忆路径。然后，它们被表示为实体、关系和时间序列的组合，并带有稀疏/密集向量表示，以辅助后续回忆。

Hindsight 提供三种简单的方法与系统交互：

• Retain（保留）：向 Hindsight 提供您希望它记住的信息
• Recall（回忆）：从 Hindsight 检索记忆
• Reflect（反思）：反思记忆和经验，从现有记忆中生成新的观察和见解。

Retain

retain 操作用于将新记忆推入 Hindsight。它告诉 Hindsight 保留 您作为输入传递的信息。

from hindsight_client import Hindsight

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

# 简单示例
client.retain(
bank_id="my-bank",
content="Alice works at Google as a software engineer"
)

# 带上下文和时间戳
client.retain(
bank_id="my-bank",
content="Alice got promoted to senior engineer",
context="career update",
timestamp="2025-06-15T10:00:00Z"
)

在幕后，retain 操作使用 LLM 提取关键事实、时间数据、实体和关系。它通过规范化过程将提取的数据转换为规范实体、时间序列、搜索索引以及元数据。这些表示为 recall 和 reflect 操作中的准确记忆检索创建了路径。

Recall

recall 操作用于检索记忆。这些记忆可以来自任何记忆类型（世界、经验等）。

from hindsight_client import Hindsight

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

# 简单示例
client.recall(bank_id="my-bank", query="What does Alice do?")

# 时间相关
client.recall(bank_id="my-bank", query="What happened in June?")

Recall 并行执行 4 种检索策略：

• 语义：向量相似度
• 关键词：BM25 精确匹配
• 图谱：实体/时间/因果链接
• 时间：时间范围过滤

检索的各个结果被合并，然后使用 reciprocal rank fusion 和交叉编码器重排序模型按相关性排序。

最终输出会根据需要进行裁剪，以适应 token 限制。

Reflect

reflect 操作用于对现有记忆进行更深入的分析。这使代理能够在记忆之间形成新的联系，并构建对其世界更全面的理解。

例如，reflect 操作可用于支持以下场景：

• AI 项目经理 反思项目中需要缓解的风险。
• 销售代理 反思为什么某些外展消息得到了回应，而其他消息没有。
• 支持代理 反思客户提出的当前产品文档未回答的问题的机会。

reflect 操作还可用于处理需要更深入思考的按需问答或分析。

from hindsight_client import Hindsight

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

client.reflect(bank_id="my-bank", query="What should I know about Alice?")

---

资源

文档：

• [***]

客户端：

• Python
• Node.js
• REST API
• CLI

社区：

• Slack
• https://github.com/vectorize-io/hindsight/issues

---

Star History

---

贡献

参见 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE

---

由 Vectorize.io 构建