Skip to content
Back to search

hindsight

MarketplaceWorks with Claude CodeGitHub

Official Hindsight integrations for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vectorize-io/hindsight with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vectorize-io/hindsight'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vectorize-io-hindsight/badge.svg)](/listings/vectorize-io-hindsight)

HTML

<a href="/listings/vectorize-io-hindsight"><img src="/api/listings/vectorize-io-hindsight/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Start a server

Docker (recommended)

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](https://hindsight.vectorize.io/developer/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](https://hindsight.vectorize.io/developer/storage) for details.

Bare metal (pip)

pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx

hindsight-api

Kubernetes (Helm)

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

Managed (no server)

[Hindsight Cloud](https://vectorize.io/pricing) 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 →](https://vectorize.io/pricing) · [Sign up →](https://ui.hindsight.vectorize.io)

All options, including Windows and air-gapped setups, are covered in the [installation guide](https://hindsight.vectorize.io/developer/installation).

2. Connect a client

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

Python

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

Node.js / TypeScript

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](https://hindsight.vectorize.io/sdks/python) · [Node.js](https://hindsight.vectorize.io/sdks/nodejs) · [Go](https://hindsight.vectorize.io/sdks/go) · [CLI](https://hindsight.vectorize.io/sdks/cli) · [REST API](https://hindsight.vectorize.io/api-reference)

Supported Platforms

| Platform | Docker | Bare Metal (pip) | Embedded DB (pg0) | |----------|--------|------------------|--------------------| | **Linux** (x86_64, ARM64) | ✅ | ✅ | ✅ |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 463 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. ![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png)
  3. [Documentation](https://hindsight.vectorize.io) • [Integrations](https://hindsight.vectorize.io/integrations) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Benchmarks](https://benchmarks.hindsight.vectorize.io/) • [Paper](https://arxiv.org/abs/2512.12818) • [Hindsight Cloud](https://ui.hindsight.vectorize.io)
  4. [![Release](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml/badge.svg)](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml)
  5. [![Version](https://img.shields.io/pypi/v/hindsight-api?logo=python&logoColor=white&label=version&color=blue)](https://pypi.org/project/hindsight-api/)
  6. [![PyPI Downloads](https://img.shields.io/pypi/dm/hindsight-client?logo=pypi&logoColor=white&label=PyPI&color=blue)](https://pypi.org/project/hindsight-client/)
  7. [![NPM Downloads](https://img.shields.io/npm/dm/%40vectorize-io%2Fhindsight-client?logo=npm&logoColor=white&label=NPM&color=blue)](https://www.npmjs.com/package/@vectorize-io/hindsight-client)
  8. [![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://vectorize.io/slack)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. <br/>
  11. <p align="center">
  12. <a href="https://www.star-history.com/vectorize-io/hindsight"><img src="https://api.star-history.com/badge?repo=vectorize-io/hindsight&type=rank" alt="Star History Rank" /> <img src="https://api.star-history.com/badge?repo=vectorize-io/hindsight&type=trending" alt="GitHub Trending Repository of the Day" /></a>
  13. </p>
  14. </div>
  15. ---
  16. ## What is Hindsight?
  17. 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.
  18. <video src="https://github.com/user-attachments/assets/923b798d-3581-4897-bb62-9cfa5a931682" controls></video>
  19. 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.
  20. > 🆕 **[Introducing Hindsight Models](https://hindsight.vectorize.io/blog/2026/11/03/hindsight-models)**: decision, rerank and embedding models built for agent memory. Open weights on [Hugging Face](https://huggingface.co/hindsight-ai), or hosted on Hindsight Inference. [Read the post →](https://hindsight.vectorize.io/blog/2026/11/03/hindsight-models)
  21. **Contents**
  22. - [Memory Performance & Accuracy](#memory-performance--accuracy)
  23. - [Quick Start](#quick-start) — [server](#1-start-a-server) · [clients](#2-connect-a-client) · [platforms](#supported-platforms) · [embedded](#python-embedded-no-server-required)
  24. - [Adding Hindsight to Your Agent](#adding-hindsight-to-your-agent) — [LLM Wrapper](#llm-wrapper-2-lines-of-code) · [integrations](#integrations) · [coding agents](#coding-agents) · [MCP](#mcp-server)
  25. - [Core Concepts](#core-concepts) — [memory types](#memory-types) · [retain / recall / reflect](#the-three-operations) · [observations](#observations) · [mental models & pages](#mental-models--pages) · [decision models](#decision-models) · [banks](#memory-banks)
  26. - [Use Cases](#use-cases)
  27. - [Running in Production](#running-in-production)
  28. - [Resources](#resources)
  29. ---
  30. ## Memory Performance & Accuracy
  31. 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:
  32. ![Overview](./hindsight-docs/static/img/hindsight-benchmarks.png)
  33. > Live, continuously updated results — including per-model accuracy, latency and cost — are published at [benchmarks.hindsight.vectorize.io](https://benchmarks.hindsight.vectorize.io/).
  34. 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](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.
  35. Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups.
  36. ---
  37. > 🤖 **Using a coding agent?** Install the Hindsight documentation skill for instant access to docs while you code:
  38. > ```bash
  39. > npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
  40. > ```
  41. > Works with Claude Code, Cursor, and other AI coding assistants.
  42. ---
  43. ## Quick Start
  44. ### 1. Start a server
  45. #### Docker (recommended)
  46. ```bash
  47. export OPENAI_API_KEY=sk-xxx
  48. docker run -it --pull always --name hindsight --restart unless-stopped -p 8888:8888 -p 9999:9999 \
  49. -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  50. -v hindsight-data:/home/hindsight/.pg0 \
  51. ghcr.io/vectorize-io/hindsight:latest
  52. ```
  53. >API: http://localhost:8888
  54. >UI: http://localhost:9999
  55. 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](https://hindsight.vectorize.io/developer/models).
  56. #### Docker (external PostgreSQL)
  57. ```bash
  58. export OPENAI_API_KEY=sk-xxx
  59. export HINDSIGHT_DB_PASSWORD=choose-a-password
  60. cd docker/docker-compose
  61. docker compose up
  62. ```
  63. > Oracle AI Database is also supported for enterprise deployments with full feature parity. See the [storage documentation](https://hindsight.vectorize.io/developer/storage) for details.
  64. #### Bare metal (pip)
  65. ```bash
  66. pip install hindsight-api
  67. export HINDSIGHT_API_LLM_API_KEY=sk-xxx
  68. hindsight-api
  69. ```
  70. #### Kubernetes (Helm)
  71. ```bash
  72. helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  73. --set api.llm.provider=openai \
  74. --set api.llm.apiKey=sk-xxx \
  75. --set postgresql.enabled=true
  76. ```
  77. #### Managed (no server)
  78. [Hindsight Cloud](https://vectorize.io/pricing) 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.
  79. [Compare self-hosted, Cloud and Enterprise →](https://vectorize.io/pricing) · [Sign up →](https://ui.hindsight.vectorize.io)
  80. All options, including Windows and air-gapped setups, are covered in the [installation guide](https://hindsight.vectorize.io/developer/installation).
  81. ### 2. Connect a client
  82. ```bash
  83. pip install hindsight-client -U # Python
  84. npm install @vectorize-io/hindsight-client # Node.js / TypeScript
  85. go get github.com/vectorize-io/hindsight/hindsight-clients/go # Go
  86. curl -fsSL https://hindsight.vectorize.io/get-cli | bash # CLI
  87. ```
  88. #### Python
  89. ```python
  90. from hindsight_client import Hindsight
  91. client = Hindsight(base_url="http://localhost:8888")
  92. # Retain: Store information
  93. client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")
  94. # Recall: Search memories
  95. client.recall(bank_id="my-bank", query="What does Alice do?")
  96. # Reflect: Generate disposition-aware response
  97. client.reflect(bank_id="my-bank", query="Tell me about Alice")
  98. ```
  99. #### Node.js / TypeScript
  100. ```javascript
  101. const { HindsightClient } = require('@vectorize-io/hindsight-client');
  102. const main = async () => {
  103. const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
  104. await client.retain('my-bank', 'Alice loves hiking in Yosemite');
  105. const results = await client.recall('my-bank', 'What does Alice like?');
  106. console.log(results);
  107. }
  108. main();
  109. ```
  110. Full reference: [Python](https://hindsight.vectorize.io/sdks/python) · [Node.js](https://hindsight.vectorize.io/sdks/nodejs) · [Go](https://hindsight.vectorize.io/sdks/go) · [CLI](https://hindsight.vectorize.io/sdks/cli) · [REST API](https://hindsight.vectorize.io/api-reference)
  111. ### Supported Platforms
  112. | Platform | Docker | Bare Metal (pip) | Embedded DB (pg0) |
  113. |----------|--------|------------------|--------------------|
  114. | **Linux** (x86_64, ARM64) | ✅ | ✅ | ✅ |
  115. | **macOS** (Apple Silicon / arm64) | ✅ | ✅ | ✅ |
  116. | **macOS** (Intel / x86_64) | ✅ | ⚠️ | ✅ |
  117. | **Windows** (x86_64) | ✅ | ✅ | ✅ |
  118. ⚠️ Intel Macs: use `hindsight-all-slim` — see the [installation guide](https://hindsight.vectorize.io/developer/installation#supported-platforms) for details.
  119. ### Python Embedded (no server required)
  120. ```bash
  121. pip install hindsight-all -U
  122. ```
  123. On Intel (x86_64) Macs, install `hindsight-all-slim` instead — see [Supported Platforms](#supported-platforms).
  124. ```python
  125. import os
  126. from hindsight import HindsightServer, HindsightClient
  127. with HindsightServer(
  128. llm_provider="openai",
  129. llm_model="gpt-5-mini",
  130. llm_api_key=os.environ["OPENAI_API_KEY"]
  131. ) as server:
  132. client = HindsightClient(base_url=server.url)
  133. client.retain(bank_id="my-bank", content="Alice works at Google")
  134. results = client.recall(bank_id="my-bank", query="Where does Alice work?")
  135. ```
  136. A [Node.js equivalent](https://hindsight.vectorize.io/sdks/hindsight-all-npm) and a [daemon CLI](https://hindsight.vectorize.io/sdks/embed) are also available.
  137. ---
  138. ## Adding Hindsight to Your Agent
  139. ### LLM Wrapper (2 lines of code)
  140. 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.
  141. ```bash
  142. pip install hindsight-litellm
  143. ```
  144. ```python
  145. from openai import OpenAI
  146. from hindsight_litellm import wrap_openai
  147. # Wrap your existing LLM client and you're done.
  148. # Defaults to Hindsight Cloud; pass hindsight_api_url for a self-hosted server.
  149. client = wrap_openai(
  150. OpenAI(),
  151. bank_id="user-123",
  152. hindsight_api_url="http://localhost:8888",
  153. )
  154. # Hindsight recalls relevant memories before the call
  155. # and retains the conversation after it.
  156. response = client.chat.completions.create(
  157. model="gpt-5-mini",
  158. messages=[{"role": "user", "content": "What do you know about me?"}],
  159. )
  160. ```
  161. `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](https://hindsight.vectorize.io/sdks/integrations/litellm).
  162. If you need explicit control over *when* memories are stored and recalled, use the [SDKs or REST API](#2-connect-a-client) directly instead.
  163. ### Integrations
  164. **60+ integrations** — most need no code changes.
  165. | | |
  166. |---|---|
  167. | **Coding agents** | [Claude Code](https://hindsight.vectorize.io/sdks/integrations/claude-code) · [Codex](https://hindsight.vectorize.io/sdks/integrations/codex) · [Cursor](https://hindsight.vectorize.io/sdks/integrations/cursor) · [GitHub Copilot](https://hindsight.vectorize.io/sdks/integrations/github-copilot) · [opencode](https://hindsight.vectorize.io/sdks/integrations/opencode) · [Cline](https://hindsight.vectorize.io/sdks/integrations/cline) · [Aider](https://hindsight.vectorize.io/sdks/integrations/aider) · [Zed](https://hindsight.vectorize.io/sdks/integrations/zed) · [Continue](https://hindsight.vectorize.io/sdks/integrations/continue) · [Roo Code](https://hindsight.vectorize.io/sdks/integrations/roo-code) · [OpenHands](https://hindsight.vectorize.io/sdks/integrations/openhands) |
  168. | **Agent frameworks** | [LangGraph / LangChain](https://hindsight.vectorize.io/sdks/integrations/langgraph) · [LlamaIndex](https://hindsight.vectorize.io/sdks/integrations/llamaindex) · [CrewAI](https://hindsight.vectorize.io/sdks/integrations/crewai) · [Pydantic AI](https://hindsight.vectorize.io/sdks/integrations/pydantic-ai) · [OpenAI Agents SDK](https://hindsight.vectorize.io/sdks/integrations/openai-agents) · [Google ADK](https://hindsight.vectorize.io/sdks/integrations/google-adk) · [Agno](https://hindsight.vectorize.io/sdks/integrations/agno) · [Strands](https://hindsight.vectorize.io/sdks/integrations/strands) · [AutoGen](https://hindsight.vectorize.io/sdks/integrations/autogen) · [Microsoft Agent Framework](https://hindsight.vectorize.io/sdks/integrations/agent-framework) · [Vercel AI SDK](https://hindsight.vectorize.io/sdks/integrations/ai-sdk) · [Haystack](https://hindsight.vectorize.io/sdks/integrations/haystack) |
  169. | **No-code / low-code** | [n8n](https://hindsight.vectorize.io/sdks/integrations/n8n) · [Zapier](https://hindsight.vectorize.io/sdks/integrations/zapier) · [Dify](https://hindsight.vectorize.io/sdks/integrations/dify) · [Flowise](https://hindsight.vectorize.io/sdks/integrations/flowise) |
  170. | **Apps & tools** | [ChatGPT](https://hindsight.vectorize.io/sdks/integrations/chatgpt) · [Perplexity](https://hindsight.vectorize.io/sdks/integrations/perplexity) · [Obsidian](https://hindsight.vectorize.io/sdks/integrations/obsidian) · [Pipecat](https://hindsight.vectorize.io/sdks/integrations/pipecat) · [Vapi](https://hindsight.vectorize.io/sdks/integrations/vapi) |
  171. 👉 [**Browse all integrations**](https://hindsight.vectorize.io/integrations)
  172. ### Coding Agents
  173. 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 pages covering architecture, conventions and in-flight work.
  174. ```bash
  175. npx @vectorize-io/hindsight-coding-agents install all # every detected agent, wired natively
  176. npx @vectorize-io/hindsight-coding-agents install claude-code # or just one
  177. ```
  178. 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](https://hindsight.vectorize.io/sdks/integrations/coding-agents).
  179. ### MCP Server
  180. Every server ships a built-in [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, one per bank, enabled by default:
  181. ```
  182. http://localhost:8888/mcp/{bank_id}/
  183. ```
  184. Point any MCP client at it to expose retain, recall and reflect as tools. See the [MCP server docs](https://hindsight.vectorize.io/developer/mcp-server).
  185. ---
  186. ## Core Concepts
  187. ![Overview](./hindsight-docs/static/img/hindsight-overview.webp)
  188. ### Memory Types
  189. 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:
  190. - **World facts:** facts about the world ("The stove gets hot")
  191. - **Experiences:** the agent's own experiences ("I touched the stove and it really hurt")
  192. - **Observations:** consolidated, evidence-backed beliefs formed from many memories
  193. - **Mental models:** learned understanding of the agent's world, synthesized from observations and facts
  194. 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.
  195. ### The Three Operations
  196. #### Retain
  197. The `retain` operation is used to push new memories into Hindsight. It tells Hindsight to _retain_ the information you pass in as an input.
  198. ```python
  199. client.retain(
  200. bank_id="my-bank",
  201. content="Alice got promoted to senior engineer",
  202. context="career update",
  203. timestamp="2025-06-15T10:00:00Z",
  204. )
  205. ```
  206. 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.
  207. <video src="https://github.com/user-attachments/assets/0555177d-6635-467d-97cb-9dcddb999b15" controls muted></video>
  208. [Retain docs →](https://hindsight.vectorize.io/developer/retain)
  209. #### Recall
  210. The recall operation is used to retrieve memories. These memories can come from any of the memory types (world, experiences, etc.)
  211. ```python
  212. client.recall(bank_id="my-bank", query="What does Alice do?")
  213. client.recall(bank_id="my-bank", query="What happened in June?") # temporal
  214. ```
  215. Recall performs 4 retrieval strategies in parallel:
  216. - Semantic: Vector similarity
  217. - Keyword: BM25 exact matching
  218. - Graph: Entity/temporal/causal links
  219. - Temporal: Time range filtering
  220. <video src="https://github.com/user-attachments/assets/1c02eac8-1c5a-4e42-9a00-7201d44975a0" controls muted></video>
  221. 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.
  222. [Recall docs →](https://hindsight.vectorize.io/developer/retrieval)
  223. #### Reflect
  224. 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.
  225. ```python
  226. client.reflect(bank_id="my-bank", query="What should I know about Alice?")
  227. ```
  228. For example, reflect supports use cases such as:
  229. - An **AI Project Manager** reflecting on what risks need to be mitigated on a project.
  230. - A **Sales Agent** reflecting on why certain outreach messages have gotten responses while others haven't.
  231. - A **Support Agent** reflecting on opportunities where customers have questions not answered by current product documentation.
  232. <video src="https://github.com/user-attachments/assets/1dd8aa20-5ad0-4536-823e-0fadf8051d57" controls muted></video>
  233. [Reflect docs →](https://hindsight.vectorize.io/developer/reflect)
  234. ### Observations
  235. 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.
  236. [Observations docs →](https://hindsight.vectorize.io/developer/observations)
  237. ### Mental Models & Pages
  238. 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.
  239. **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.
  240. [Mental models →](https://hindsight.vectorize.io/developer/mental-models) · [Pages →](https://hindsight.vectorize.io/developer/pages)
  241. ### Decision Models
  242. Most of what a memory system does between storing and recalling is small judgments: is this fact new, which of these memories matter for the question, could this change a page. A **decision model** answers those directly, with a typed answer instead of text to parse, so Hindsight sends far fewer of them to your LLM. Turn it on and recall, consolidation, reflect and pages use it.
  243. | Model | What it does | Size | License |
  244. |---|---|---|---|
  245. | [`hs-decide-1-flash`](https://huggingface.co/hindsight-ai/hs-decide-1-flash) | Decision model: the judgments inside recall, consolidation, reflect and pages | 0.8B | Apache 2.0 |
  246. | [`hs-rerank-1`](https://huggingface.co/hindsight-ai/hs-rerank-1) | Reranker: orders recalled memories by relevance | 114M | MIT |
  247. | [`hs-embed-1`](https://huggingface.co/hindsight-ai/hs-embed-1) | Embeddings: 384-dimensional vectors for search | 112M | MIT |
  248. All three read eight languages. Run them yourself, or use them hosted on Hindsight Inference:
  249. ```bash
  250. hindsight-admin cloud login
  251. export HINDSIGHT_API_DECISION_MODEL_PROVIDER=hindsight
  252. ```
  253. [Decision models docs →](https://hindsight.vectorize.io/developer/decision-models) · [Launch post →](https://hindsight.vectorize.io/blog/2026/11/03/hindsight-models)
  254. ### Memory Banks
  255. 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](https://hindsight.vectorize.io/developer/api/bank-templates).
  256. Two more things worth knowing:
  257. - **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 →](https://hindsight.vectorize.io/developer/multilingual)
  258. - **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 →](https://hindsight.vectorize.io/developer/memory-defense)
  259. ---
  260. ## Use Cases
  261. 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.
  262. ### Per-User Memories and Chat History
  263. 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.
  264. The requirements for this use case usually look something like this:
  265. ![Per-User Memories](./hindsight-docs/static/img/per-user-memory-requirements.png)
  266. <video src="https://github.com/user-attachments/assets/4805e8e1-e7d1-47c6-a4f8-2344a5ec8906" controls></video>
  267. 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.
  268. ![Per-User Memories](./hindsight-docs/static/img/per-user-memory-howto.png)
  269. More patterns in the [Cookbook](https://hindsight.vectorize.io/cookbook) and [Best Practices](https://hindsight.vectorize.io/best-practices).
  270. ---
  271. ## Running in Production
  272. | | |
  273. |---|---|
  274. | **Storage** | PostgreSQL + pgvector, or Oracle AI Database 23ai with full feature parity — [storage](https://hindsight.vectorize.io/developer/storage) |
  275. | **Configuration** | Hierarchical: global env vars → per-tenant → per-bank — [configuration](https://hindsight.vectorize.io/developer/configuration) |
  276. | **Monitoring** | Prometheus metrics and dashboards for LLM calls, tokens and latency — [monitoring](https://hindsight.vectorize.io/developer/monitoring) |
  277. | **Operations** | Admin CLI for migrations, bank repair and stuck operations — [admin CLI](https://hindsight.vectorize.io/developer/admin-cli) |
  278. | **Events** | Webhooks for retain, consolidation and refresh lifecycle events — [webhooks](https://hindsight.vectorize.io/developer/api/webhooks) |
  279. | **Extensibility** | Tenant, auth and storage extension points — [extensions](https://hindsight.vectorize.io/developer/extensions) |
  280. | **Managed** | Skip all of it with [Hindsight Cloud](https://vectorize.io/pricing) — managed, usage-based, 99.9% uptime SLA |
  281. ---
  282. ## Resources
  283. **Documentation:**
  284. - [Docs](https://hindsight.vectorize.io) · [FAQ](https://hindsight.vectorize.io/faq) · [Best Practices](https://hindsight.vectorize.io/best-practices) · [Cookbook](https://hindsight.vectorize.io/cookbook) · [Blog](https://hindsight.vectorize.io/blog)
  285. - [Paper](https://arxiv.org/abs/2512.12818) · [Benchmarks](https://benchmarks.hindsight.vectorize.io/) · [RAG vs Memory](https://hindsight.vectorize.io/developer/rag-vs-hindsight)
  286. **Clients:**
  287. - [Python](https://hindsight.vectorize.io/sdks/python) · [Node.js](https://hindsight.vectorize.io/sdks/nodejs) · [Go](https://hindsight.vectorize.io/sdks/go) · [CLI](https://hindsight.vectorize.io/sdks/cli) · [REST API](https://hindsight.vectorize.io/api-reference)
  288. **Community:**
  289. - [Slack](https://vectorize.io/slack)
  290. - [GitHub Issues](https://github.com/vectorize-io/hindsight/issues)
  291. ---
  292. ## Star History
  293. [![Star History Chart](https://api.star-history.com/chart?repos=vectorize-io/hindsight&type=date&legend=top-left)](https://www.star-history.com/?repos=vectorize-io%2Fhindsight&type=date&legend=top-left)
  294. ---
  295. ## Contributing
  296. See [CONTRIBUTING.md](./CONTRIBUTING.md).
  297. ## License
  298. MIT — see [LICENSE](./LICENSE)
  299. ---
  300. Built by [Vectorize.io](https://vectorize.io)
  301. <img src="https://umami-pixel.chris-latimer.workers.dev/?id=a8b043e6-6964-454d-80df-69b69d3f0d50&host=github.com&url=/vectorize-io/hindsight" width="1" height="1" alt="" />

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.