Hindsight — Agent Memory That Learns

What it claims

Hindsight organizes memory with four "biomimetic" types rather than flat vector search: world facts ("the stove gets hot"), experiences (the agent's own actions), observations (deduplicated, evidence-backed beliefs consolidated from many memories), and mental models (synthesized standing answers). The summary names retain/recall/reflect; the page explains what each actually does and how observations and mental models differ from ordinary recall.

How it works

• retain runs an LLM over your input to extract facts, temporal data, entities, and relationships, normalizes them to canonical entities/time-series/search indexes with metadata.
• recall runs four retrieval strategies in parallel — semantic (vector), keyword (BM25), graph (entity/temporal/causal links), and temporal (time-range filter) — then merges via reciprocal rank fusion plus a cross-encoder reranker, trimmed to a token budget.
• reflect does deeper analysis, forming new connections for questions that need reasoning rather than lookup; bank-level disposition traits (skepticism, literalism, empathy) shape how it reasons.

Two mechanisms distinguish it from RAG: observations are refined (strengthened/weakened/extended) rather than overwritten when new evidence arrives, keeping exact supporting quotes and a proof count. Mental models / knowledge pages are pre-written standing answers — reading one is a plain DB read (no retrieval, no LLM call), so an agent boots with settled knowledge instead of re-deriving it each session.

Memory lives in banks — strictly isolated stores, one per user/agent/project.

How to use it

Run the server:

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

Drop-in memory via the LLM Wrapper — no other code changes:

from openai import OpenAI
from hindsight_litellm import wrap_openai
client = wrap_openai(OpenAI(), bank_id="user-123", hindsight_api_url="http://localhost:8888")

wrap_anthropic() mirrors it; LiteLLM underneath covers 100+ models. Works with 25+ LLM providers including fully local (ollama, lmstudio, llamacpp) and existing subscriptions (claude-code, openai-codex, cursor, github-copilot) with no API key. Clients: Python/Node/Go/CLI. Every server ships a built-in MCP endpoint per bank at http://localhost:8888/mcp/{bank_id}/. Storage backends: Postgres or Oracle AI Database (enterprise, full parity).

For coding agents, one package builds a per-repo bank from git history and past sessions:

npx @vectorize-io/hindsight-coding-agents install all

Supports Claude Code, Codex CLI, Cursor CLI, Copilot CLI, opencode, and ~10 others.

Worth knowing

• Multilingual by default: input language and native script are preserved end to end (张伟 stays 张伟, not "Zhang Wei").
• Memory Defense (opt-in, per-bank): scans every retain against 45 secret/PII patterns and either redacts ([REDACTED:github_token]) or blocks before storage.

Limits

Benchmark numbers themselves are not in the fetched text — only the claim of SOTA on LongMemEval "as of January 2026," with live per-model accuracy/latency/cost at benchmarks.hindsight.vectorize.io; non-Hindsight scores are self-reported by vendors. The authors state Hindsight "may be overkill" for simple workflows (e.g., n8n) and position it for open-ended, learning agents. Check the actual leaderboard numbers and the paper before adopting — this page asserts the result without stating the figure or baselines.