---

Hindsight 是什么？

Hindsight™ 是一个智能体记忆系统，旨在构建能够随时间不断学习的更智能的智能体。大多数智能体记忆系统专注于回忆对话历史，而 Hindsight 则专注于让智能体不仅记住，还能真正地学习。

它克服了 RAG 和知识图谱等替代技术的不足，在长期记忆任务上实现了最先进的性能。

记忆性能与准确性

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

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

Hindsight 目前已被财富 500 强企业和越来越多的 AI 创业公司投入生产使用。

将 Hindsight 添加到您的 AI 智能体中

将 Hindsight 与现有智能体结合使用的最简单方法是使用 LLM 包装器。只需两行代码即可为您的智能体添加记忆功能，这会将您当前的 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 --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。更多关于支持模型的信息，请参阅文档：https://hindsight.vectorize.io/developer/models。

Docker（外置 PostgreSQL）

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

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 在 Google 担任软件工程师")

# Recall：搜索记忆
client.recall(bank_id="my-bank", query="Alice 是做什么的？")

# Reflect：生成考虑情境的响应
client.reflect(bank_id="my-bank", query="给我讲讲 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 喜欢去优胜美地徒步')；

  const results = await client.recall('my-bank', 'Alice 喜欢什么？');
  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 在 Google 工作")
    results = client.recall(bank_id="my-bank", query="Alice 在哪里工作？")

---

使用场景

Hindsight 旨在支持对话式 AI 智能体以及那些计划自主执行任务的智能体。Hindsight 的理想应用场景是那些需要兼具这些功能的智能体，例如能够处理开放式任务、根据用户反馈调整行为，并学习完成复杂任务以实现接近人类水平自动化工作的 AI 员工。Hindsight 可以与 n8n 等类似工具构建的简单 AI 工作流一起使用，但对于此类应用来说可能有些过于强大了。

每个用户的记忆与聊天记录

你可以使用 Hindsight 的一个较为简单的用例，就是通过存储和调用与单个用户相关的记忆，来个性化 AI 聊天机器人和其他对话式智能体。

此用例的需求通常如下所示：

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

---

架构与操作

大多数智能体记忆实现依赖于基础向量搜索，有时也会使用知识图谱。而 Hindsight 则采用仿生数据结构来组织智能体记忆，其方式更接近人类记忆的工作机制：

• 世界： 关于世界的事实（“炉子会变热”）
• 经历： 智能体自身的经历（“我摸了炉子一下，真的很疼”）
• 心智模型： 通过对原始记忆和经历进行反思而形成的对智能体所处世界的理解。

Hindsight 中的记忆被存储在记忆库中。当记忆被添加到 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 在 Google 担任软件工程师"
)

# 带上下文和时间戳的示例
client.retain(
    bank_id="my-bank",
    content="Alice 被晋升为高级工程师",
    context="职业更新",
    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="Alice 是做什么的？")

# 时间相关的示例
client.recall(bank_id="my-bank", query="六月份发生了什么？")

Recall 会并行执行四种检索策略：

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

各个检索结果会被合并，然后根据相关性使用倒排秩融合和交叉编码器重排序模型进行排序。

最终输出会根据需要进行截断，以符合 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="关于 Alice 我应该知道些什么？")

---

资源

文档：

• https://hindsight.vectorize.io

客户端：

• Python
• Node.js
• REST API
• CLI

社区：

• Slack
• GitHub Issues

---

星标历史

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE

---

由 Vectorize.io 构建

Hindsight 快速上手指南

Hindsight 是一个专为 AI Agent 设计的记忆系统。与传统的仅记录对话历史的方案不同，Hindsight 旨在让 Agent 具备“学习”能力，通过模拟人类记忆机制（世界事实、个人经历、心智模型）来实现长期的知识积累与推理。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需安装 Docker Desktop)。
• 核心依赖：
  • Docker (推荐方式) 或 Python 3.9+ / Node.js 18+。
  • 有效的 LLM API Key (支持 OpenAI, Anthropic, Gemini, Groq, Ollama 等)。
• 网络环境：确保能够访问 ghcr.io (GitHub Container Registry) 或配置了相应的国内镜像加速。

安装步骤

方式一：使用 Docker 部署（推荐）

这是最快捷的启动方式，无需配置本地数据库，数据将持久化存储在本地目录。

1. 设置环境变量（替换为你的 API Key）：

   export OPENAI_API_KEY=sk-xxx
   

   注：如需使用其他模型提供商，可额外设置 export HINDSIGHT_API_LLM_PROVIDER=anthropic (可选值：openai, anthropic, gemini, groq, ollama, lmstudio, minimax)。

2. 运行 Docker 容器：

   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

方式二：Python 嵌入式模式（无需服务器）

如果你希望在代码中直接运行轻量级实例，无需单独部署服务器：

1. 安装依赖包：

   pip install hindsight-all -U
   

2. 确保已设置 OPENAI_API_KEY 环境变量。

基本使用

Hindsight 提供三个核心操作：Retain (存储记忆)、Recall (检索记忆)、Reflect (反思/生成洞察)。

1. Python 客户端使用示例

首先安装官方客户端：

pip install hindsight-client -U

代码示例：

from hindsight_client import Hindsight

# 初始化客户端，指向本地服务
client = Hindsight(base_url="http://localhost:8888")

# 1. Retain: 存储信息到记忆库 (bank_id 用于隔离不同用户或场景)
client.retain(
    bank_id="my-bank", 
    content="Alice works at Google as a software engineer"
)

# 2. Recall: 根据查询检索相关记忆
results = client.recall(
    bank_id="my-bank", 
    query="What does Alice do?"
)
print(results)

# 3. Reflect: 基于现有记忆进行深度分析并生成回答
response = client.reflect(
    bank_id="my-bank", 
    query="Tell me about Alice's career path"
)
print(response)

2. 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' });

  // 1. Retain: 存储记忆
  await client.retain('my-bank', 'Alice loves hiking in Yosemite');

  // 2. Recall: 检索记忆
  const results = await client.recall('my-bank', 'What does Alice like?');
  console.log(results);
}

main();

3. Python 嵌入式模式示例

如果你选择了“方式二”安装，可以直接在脚本中启动服务：

import os
from hindsight import HindsightServer, HindsightClient

# 在上下文管理器中启动临时服务器
with HindsightServer(
    llm_provider="openai",
    llm_model="gpt-4o-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?")
    print(results)

---

更多高级用法（如自定义元数据过滤、时间序列查询）请参考官方文档：https://hindsight.vectorize.io