Hindsight：让 Agent 随时间学习的记忆系统

---

Hindsight™ 是一套 Agent 记忆系统，旨在构建能够随时间变得更聪明、持续学习的 Agent。大多数 Agent 记忆系统专注于回忆对话历史；Hindsight 则专注于让 Agent 学习，而不只是记住。

视频：Hindsight 学习演示

它消除了 RAG 和知识图谱等替代技术的缺陷，并在长期记忆任务中实现了当前最佳性能。

目录

---

记忆性能与准确性

根据基准测试表现，Hindsight 是迄今测试过的准确性最高的 Agent 记忆系统。它在广泛用于评估多种对话式 AI 场景中记忆系统性能的 LongMemEval 基准上取得了当前最佳表现。下图展示了截至 2026 年 1 月 Hindsight 与其他 Agent 记忆解决方案的当前报告性能：

实时、持续更新的结果——包括按模型划分的准确率、延迟和成本——发布于 benchmarks.hindsight.vectorize.io。

Hindsight 的基准性能数据已由 Virginia Tech Sanghani Center for Artificial Intelligence and Data Analytics 以及《华盛顿邮报》的研究合作方独立复现。其他评分由软件供应商自行报告。

Hindsight 已在《财富》500 强企业及越来越多的 AI 创业公司中投入生产使用。

---

🤖 正在使用编码 Agent？ 安装 Hindsight 文档技能，即可在编码时即时访问文档：

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

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

---

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 通过 HINDSIGHT_API_LLM_PROVIDER 支持 25 家以上 LLM 提供商——托管服务（openai、anthropic、gemini、groq、bedrock、vertexai、minimax、deepseek、atlas、meta 等）、完全本地部署（ollama、lmstudio、llamacpp）、任意 OpenAI 兼容端点，以及能够连接其余服务的网关（litellm、litellmrouter）。现有订阅同样可用：openai-codex（ChatGPT Plus/Pro）、claude-code（Claude Pro/Max）、cursor（Cursor）和 github-copilot（GitHub Copilot）无需 API 密钥。请参阅支持的模型。

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 也支持具备完整功能对等性的企业部署。详情请参阅存储文档。

pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx

hindsight-api

helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  --set api.llm.provider=openai \
  --set api.llm.apiKey=sk-xxx \
  --set postgresql.enabled=true

Hindsight Cloud 是托管选项：提供可自动扩缩容的托管基础设施，以及仪表盘、备份、团队协作和 99.9% 正常运行时间 SLA。其按使用量计费，提供免费起步额度——没有固定月费或按席位收费。只需使用 API 密钥将任意客户端指向 https://api.hindsight.vectorize.io，即可完全跳过部署流程。

对比自托管、Cloud 与 Enterprise → · 注册 →

包括 Windows 和隔离网络环境部署在内的全部选项，均可在安装指南中查阅。

pip install hindsight-client -U                                  # Python
npm install @vectorize-io/hindsight-client                        # Node.js / TypeScript
go get github.com/vectorize-io/hindsight/hindsight-clients/go     # Go
curl -fsSL https://hindsight.vectorize.io/get-cli | bash          # CLI

from hindsight_client import Hindsight

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

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

# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")

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 · Node.js · Go · CLI · REST API

平台	Docker	裸机（pip）	嵌入式数据库（pg0）
Linux（x86_64、ARM64）	✅	✅	✅
macOS（Apple Silicon / arm64）	✅	✅	✅
macOS（Intel / x86_64）	✅	⚠️	✅
Windows（x86_64）	✅	✅	✅

⚠️ Intel Mac：请使用 hindsight-all-slim——详情参阅安装指南。

Python 嵌入式部署（无需服务器）

pip install hindsight-all -U

在 Intel（x86_64）Mac 上，请改为安装 hindsight-all-slim——参阅支持的平台。

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?")

此外还提供 Node.js 等效方案和 daemon CLI。

---

将 Hindsight 添加到你的 Agent

LLM Wrapper（2 行代码）

为现有 Agent 添加记忆的最简单方式是 LLM Wrapper。将你的 LLM 客户端替换为封装后的客户端——此后每次调用都会自动存储和检索记忆，无需对代码进行其他修改。

pip install hindsight-litellm

from openai import OpenAI
from hindsight_litellm import wrap_openai

# Wrap your existing LLM client and you're done.
# Defaults to Hindsight Cloud; pass hindsight_api_url for a self-hosted server.
client = wrap_openai(
    OpenAI(),
    bank_id="user-123",
    hindsight_api_url="http://localhost:8888",
)

# Hindsight recalls relevant memories before the call
# and retains the conversation after it.
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "What do you know about me?"}],
)

wrap_anthropic() 可为 Anthropic SDK 提供相同能力；每项设置——包括 bank、recall 预算、事实类型，以及以 reflect 替代 recall——均可通过 hindsight_* kwargs 按单次调用覆盖。底层采用 LiteLLM，因此同一套集成可覆盖 100 多个模型。请参阅 LiteLLM 集成。

如果你需要明确控制记忆的存储和调用时机，请直接使用 SDK 或 REST API。

60 多项集成——其中大多数无需修改代码。

👉 浏览全部集成

单个软件包可为 CLI 编码 Agent 提供长期项目记忆：系统会从 git 历史和过往会话中自动构建每个仓库对应的 bank，在 Agent 开始工作时注入其中；同时提供涵盖架构、约定和进行中工作的精选知识页面。

npx @vectorize-io/hindsight-coding-agents install all          # every detected agent, wired natively
npx @vectorize-io/hindsight-coding-agents install claude-code  # or just one

支持 Claude Code、Codex CLI、Cursor CLI、GitHub Copilot CLI、opencode、Kilo CLI、Cline CLI、Antigravity CLI、Devin CLI、pi、Prime Agent、Grok Build 和 DeepSeek Harness。摄取过程自动完成——无需运行设置命令。请参阅编码 Agent 集成。

每个服务器均内置一个 Model Context Protocol 端点，每个 bank 对应一个端点，默认启用：

http://localhost:8888/mcp/{bank_id}/

将任意 MCP 客户端指向该端点，即可将 retain、recall 和 reflect 暴露为工具。请参阅 MCP 服务器文档。

---

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

• 世界事实： 关于世界的事实（“炉子会变热”）
• 经历： Agent 自身的经历（“我碰了炉子，真的很痛”）
• 观察结论： 由多条记忆形成、具有证据支撑的整合性信念
• 心理模型： 从观察结论和事实中综合而成的、Agent 对其世界的学习式理解

记忆存储在 banks 中。添加记忆时，信息会被推送至世界事实或经历路径之一，随后被表示为实体、关系和时间序列的组合，并使用稀疏／稠密向量表示来帮助后续调用。

retain 操作用于将新记忆写入 Hindsight。它会告知 Hindsight 将你传入的信息作为输入进行_保留_。

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 操作中的准确记忆检索建立了路径。

视频：Hindsight retain 操作说明

Retain 文档 →

recall 操作用于检索记忆。这些记忆可来自任意记忆类型（世界事实、经历等）。

client.recall(bank_id="my-bank", query="What does Alice do?")
client.recall(bank_id="my-bank", query="What happened in June?")   # temporal

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

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

视频：Hindsight recall 操作说明

各项结果将被合并，使用倒数排名融合（reciprocal rank fusion）和交叉编码器重排序模型按相关性排序，然后根据需要裁剪，以适配 token 限制。

Recall 文档 →

reflect 操作会对现有记忆执行更深入的分析。这使 Agent 能够在记忆之间建立新关联，并形成对其世界更全面的理解——或回答需要深度思考、而非简单查找的问题。

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

例如，reflect 支持以下用例：

• 一名 AI 项目经理 反思项目中有哪些风险需要缓解。
• 一名 销售 Agent 反思为何某些外联消息获得了回复，而其他消息没有。
• 一名 支持 Agent 反思客户提出、但当前产品文档尚未解答的问题所带来的机会。

视频：Hindsight reflect 操作说明

Reflect 文档 →

保留的事实不会始终只是平铺的信息堆。在后台，Hindsight 会将相关事实整合为 观察结论——即 bank 随时间形成的、已去重的信念。每项观察结论都会保留其支持证据，包括精确引用和证明计数；当新证据到来时，它会被_优化_而非覆盖。因此，新信息会增强、削弱或扩展既有信念，而不是在无声中将其替换。

观察结论文档 →

心理模型与知识页面

心理模型 是对某个 bank 问题的长期答案（例如“该用户有哪些偏好？”）。你只需定义一次问题；Hindsight 会生成答案、存储答案，并在 bank 学习到更多信息时在后台重写答案。读取心理模型只是一项数据库读取操作——无需检索，也无需 LLM 调用——因此，Agent 可以带着一页已沉淀的知识启动，而不必在每个会话中重新发现这些信息。

知识页面

---

Hindsight™ is an agent memory system built to create smarter agents that learn over time. Most agent memory systems focus on recalling conversation history. Hindsight is focused on making agents that learn, not just remember.

hindsight-learning-demo.mp4

It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.

Contents

---

Memory Performance & Accuracy

Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here:

Live, continuously updated results — including per-model accuracy, latency and cost — are published at benchmarks.hindsight.vectorize.io.

The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech Sanghani Center for Artificial Intelligence and Data Analytics and The Washington Post. Other scores are self-reported by software vendors.

Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups.

---

🤖 Using a coding agent? Install the Hindsight documentation skill for instant access to docs while you code:

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

Works with Claude Code, Cursor, and other AI coding assistants.

---

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 works with 25+ LLM providers via HINDSIGHT_API_LLM_PROVIDER — hosted (openai, anthropic, gemini, groq, bedrock, vertexai, minimax, deepseek, atlas, meta, …), fully local (ollama, lmstudio, llamacpp), any OpenAI-compatible endpoint, and gateways (litellm, litellmrouter) that reach the rest. Existing subscriptions work too: openai-codex (ChatGPT Plus/Pro), claude-code (Claude Pro/Max), cursor (Cursor) and github-copilot (GitHub Copilot) need no API key. See supported models.

Docker (external PostgreSQL)

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

Oracle AI Database is also supported for enterprise deployments with full feature parity. See the storage documentation for details.

pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx

hindsight-api


helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  --set api.llm.provider=openai \
  --set api.llm.apiKey=sk-xxx \
  --set postgresql.enabled=true

Hindsight Cloud is the hosted option: managed infrastructure that scales automatically, plus a dashboard, backups, team collaboration and a 99.9% uptime SLA. Billing is usage-based with free credits to start — no fixed monthly or per-seat fee. Point any client at https://api.hindsight.vectorize.io with your API key and skip the deployment entirely.

Compare self-hosted, Cloud and Enterprise → · Sign up →

All options, including Windows and air-gapped setups, are covered in the installation guide.

pip install hindsight-client -U                                  # Python
npm install @vectorize-io/hindsight-client                        # Node.js / TypeScript
go get github.com/vectorize-io/hindsight/hindsight-clients/go     # Go
curl -fsSL https://hindsight.vectorize.io/get-cli | bash          # CLI


from hindsight_client import Hindsight

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

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

# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")


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();

Full reference: Python · Node.js · Go · CLI · REST API

Platform	Docker	Bare Metal (pip)	Embedded DB (pg0)
Linux (x86_64, ARM64)	✅	✅	✅
macOS (Apple Silicon / arm64)	✅	✅	✅
macOS (Intel / x86_64)	✅	⚠️	✅
Windows (x86_64)	✅	✅	✅

⚠️ Intel Macs: use hindsight-all-slim — see the installation guide for details.

Python Embedded (no server required)

pip install hindsight-all -U

On Intel (x86_64) Macs, install hindsight-all-slim instead — see Supported Platforms.

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?")

A Node.js equivalent and a daemon CLI are also available.

---

Adding Hindsight to Your Agent

LLM Wrapper (2 lines of code)

The easiest way to add memory to an existing agent is the LLM Wrapper. Swap your LLM client for a wrapped one — memories are then stored and retrieved automatically on every call, with no other changes to your code.

pip install hindsight-litellm


from openai import OpenAI
from hindsight_litellm import wrap_openai

# Wrap your existing LLM client and you're done.
# Defaults to Hindsight Cloud; pass hindsight_api_url for a self-hosted server.
client = wrap_openai(
    OpenAI(),
    bank_id="user-123",
    hindsight_api_url="http://localhost:8888",
)

# Hindsight recalls relevant memories before the call
# and retains the conversation after it.
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "What do you know about me?"}],
)

wrap_anthropic() does the same for the Anthropic SDK, and every setting — bank, recall budget, fact types, reflect instead of recall — can be overridden per call with hindsight_* kwargs. LiteLLM sits underneath, so the same integration covers 100+ models. See the LiteLLM integration.

If you need explicit control over when memories are stored and recalled, use the SDKs or REST API directly instead.

60+ integrations — most need no code changes.

👉 Browse all integrations

One package gives CLI coding agents long-term project memory: a per-repo bank built automatically from git history and past sessions, injected into the agent as it starts working, plus curated knowledge pages covering architecture, conventions and in-flight work.

npx @vectorize-io/hindsight-coding-agents install all          # every detected agent, wired natively
npx @vectorize-io/hindsight-coding-agents install claude-code  # or just one

Supports Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI, opencode, Kilo CLI, Cline CLI, Antigravity CLI, Devin CLI, pi, Prime Agent, Grok Build and DeepSeek Harness. Ingestion is automatic — there is no setup command. See the coding agents integration.

Every server ships a built-in Model Context Protocol endpoint, one per bank, enabled by default:

http://localhost:8888/mcp/{bank_id}/

Point any MCP client at it to expose retain, recall and reflect as tools. See the MCP server docs.

---

Most agent memory implementations rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:

• World facts: facts about the world ("The stove gets hot")
• Experiences: the agent's own experiences ("I touched the stove and it really hurt")
• Observations: consolidated, evidence-backed beliefs formed from many memories
• Mental models: learned understanding of the agent's world, synthesized from observations and facts

Memories live in banks. When memories are added, they are pushed into either the world facts or the experiences pathway, then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.

The retain operation is used to push new memories into Hindsight. It tells Hindsight to retain the information you pass in as an input.

client.retain(
    bank_id="my-bank",
    content="Alice got promoted to senior engineer",
    context="career update",
    timestamp="2025-06-15T10:00:00Z",
)

Behind the scenes, retain uses an LLM to extract key facts, temporal data, entities, and relationships. It passes these through a normalization process to transform extracted data into canonical entities, time series, and search indexes along with metadata. These representations create the pathways for accurate memory retrieval in the recall and reflect operations.

what-hindsight-does-retain.mp4

Retain docs →

The recall operation is used to retrieve memories. These memories can come from any of the memory types (world, experiences, etc.)

client.recall(bank_id="my-bank", query="What does Alice do?")
client.recall(bank_id="my-bank", query="What happened in June?")   # temporal

Recall performs 4 retrieval strategies in parallel:

• Semantic: Vector similarity
• Keyword: BM25 exact matching
• Graph: Entity/temporal/causal links
• Temporal: Time range filtering

what-hindsight-does-recall.mp4

The individual results are merged, ordered by relevance using reciprocal rank fusion and a cross-encoder reranking model, then trimmed as needed to fit within the token limit.

Recall docs →

The reflect operation performs a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world — or to answer a question that needs deep thinking rather than lookup.

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

For example, reflect supports use cases such as:

• An AI Project Manager reflecting on what risks need to be mitigated on a project.
• A Sales Agent reflecting on why certain outreach messages have gotten responses while others haven't.
• A Support Agent reflecting on opportunities where customers have questions not answered by current product documentation.

what-hindsight-does-reflect.mp4

Reflect docs →

Retained facts don't stay a flat pile. In the background, Hindsight consolidates related facts into observations — deduplicated beliefs the bank has built up over time. Each observation keeps its supporting evidence with exact quotes and a proof count, and is refined rather than overwritten when new evidence arrives, so new information strengthens, weakens or extends an existing belief instead of silently replacing it.

Observations docs →

Mental Models & Knowledge Pages

A mental model is a standing answer to a question about a bank ("What are this user's preferences?"). You define the question once; Hindsight writes the answer, stores it, and rewrites it in the background as the bank learns more. Reading one is a database read — no retrieval, no LLM call — so an agent can boot with a page of settled knowledge instead of rediscovering it every session.

Knowledge pages are mental models with the mechanics hidden: living documents a bank writes about itself, organized in folders like a wiki, searchable, and projectable onto disk as ordinary markdown. Supply a name and a question; every other decision is a default you can override.

Mental models → · Knowledge pages →

A bank is an isolated memory store — one "brain" for one user, agent, or project. Isolation is strict: no cross-bank leakage. Banks carry background context and disposition traits (skepticism, literalism, empathy) that shape how reflect reasons over their memories, and can be created from declarative bank templates.

Two more things worth knowing:

• Multilingual by default. Input language is detected and preserved end to end — facts stay in their original language and entities keep their native script (张伟 stays 张伟, not "Zhang Wei"). Docs →
• Memory Defense. An opt-in, per-bank policy that scans every retain for secrets and PII against 45 patterns and either redacts the match ([REDACTED:github_token]) or blocks the item before it reaches storage. Docs →

---

Hindsight is built to support conversational AI agents as well as agents that are intended to perform tasks autonomously. The ideal use case for Hindsight are agents that require a blend of these features such as AI employees that need to handle open-ended tasks, change behavior based on user feedback, and learn to perform complex tasks to automate work at a level that approximates a human work. Hindsight can be used with simple AI workflows like those built with n8n and other similar tools, but may be overkill for such applications.

Per-User Memories and Chat History

One of the simpler use cases you can use Hindsight for is to personalize AI chatbots and other conversational agents by storing and recalling memories associated with individual users.

The requirements for this use case usually look something like this:

per-user-memory.mp4

Satisfying these requirements in Hindsight is straightforward. When new user inputs and tool calls are ingested into Hindsight using the retain operation, custom metadata can be used to enrich the new memories. Metadata provides a convenient way to isolate memories that need to be restricted to a given user. Once these are fed into the retain operation, any raw memories and mental models that get created can be filtered when retrieving relevant memories.

More patterns in the Cookbook and Best Practices.

---

|
---|---
Storage | PostgreSQL + pgvector, or Oracle AI Database 23ai with full feature parity — storage
Configuration | Hierarchical: global env vars → per-tenant → per-bank — configuration
Monitoring | Prometheus metrics and dashboards for LLM calls, tokens and latency — monitoring
Operations | Admin CLI for migrations, bank repair and stuck operations — admin CLI
Events | Webhooks for retain, consolidation and refresh lifecycle events — webhooks
Extensibility | Tenant, auth and storage extension points — extensions
Managed | Skip all of it with Hindsight Cloud — managed, usage-based, 99.9% uptime SLA

---

Documentation:

Clients:

Community:

---

---

See CONTRIBUTING.md.

MIT — see LICENSE

---

Built by Vectorize.io