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

什么是 Hindsight？

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

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

记忆性能与准确性

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

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

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

将 Hindsight 添加到您的 AI 代理

将 Hindsight 与现有代理结合使用的最简单方法是通过 LLM Wrapper。您只需 2 行代码即可为代理添加记忆功能。这将把您当前的 LLM 客户端替换为 Hindsight 包装器。之后，在进行 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 -it --pull always --name hindsight --restart unless-stopped -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 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 种检索策略：

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

检索结果被合并，然后使用 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 构建