Who hindsight is for#
Developers building production AI agents with session persistence
Hindsight's retain/recall/reflect API slots into any Python, TypeScript, or Go agent that needs to remember user preferences, past decisions, and learned facts across sessions. The LLM Wrapper makes it a two-line change for existing OpenAI or Anthropic clients.
Skip if:
Skip if your agent only needs within-session context or can store state in a database your application code already manages. Hindsight adds value when you need cross-session memory with temporal and entity reasoning, not just conversation history lookup.
Teams deploying coding agents with project memory
The coding-agents package automatically builds a per-repo memory bank from git history and past sessions. On each run, the agent receives curated knowledge pages covering architecture, conventions, and in-progress work, reducing repeated context-setting in long-lived projects.
Skip if:
Skip if your coding agent workflows are short and self-contained enough that CLAUDE.md or similar context files already capture all project conventions. Hindsight's per-repo memory adds most value for long-running projects with frequent sessions.
AI product teams who need data ownership and no API pricing risk
Self-hosting removes per-query billing exposure and keeps memory data on internal infrastructure. The MIT license allows modification without license restrictions, and the deployment options (Docker, pip, Helm, embedded) cover most production stack shapes.
Skip if:
Skip if your team cannot maintain a persistent server. Hindsight Cloud (the managed option) removes this burden, but re-introduces per-usage billing similar to Mem0 or Zep.
Enterprises building support or sales agents with per-user memory banks
Memory banks scope memory to a user or account, and bank configuration supports compliance rules via Directives. The reflect operation consolidates knowledge over time so agents carry an up-to-date model of each user without re-reading full conversation history.
Skip if:
Skip if your compliance or data residency requirements forbid storing user data in a self-hosted internal system; consult your legal team before deploying any persistent memory layer.
The problem it solves#
AI agents lose all context between sessions. Every new conversation starts without memory of past preferences, prior decisions, or learned facts, forcing users to re-explain their situation repeatedly or agents to make recommendations that ignore what has already been tried.
The challenge goes deeper than storing conversation history. Simple vector search cannot answer time-range queries like 'What did Alice do last spring?', cannot reason across disconnected facts (knowing that Alice works at Google and that Google is in Mountain View does not automatically imply where Alice lives), and cannot detect when newer information contradicts older stored facts. Teams building production agents often cobble together vector databases and custom retrieval logic to paper over these gaps, producing brittle pipelines that do not handle knowledge conflicts or temporal context.
How it solves it#
TEMPR Four-Arm Retrieval
Recall runs semantic vector search, BM25 keyword matching, entity graph traversal, and temporal range filtering in parallel. Results are merged with reciprocal rank fusion, re-ranked by a cross-encoder that reads the query alongside each memory, then trimmed to the token budget. This covers queries that pure vector search misses: exact names, date ranges, and entity relationships.
Four-Tier Memory Hierarchy
Memories are organized as world facts (objective information), experience facts (the agent's own actions), observations (automatically consolidated beliefs with evidence tracking and conflict resolution), and mental models (curated summaries for recurring query patterns). During reflect, the agent checks this hierarchy in priority order before falling back to raw facts.
Observation Consolidation with Conflict Resolution
When new facts arrive, Hindsight automatically merges overlapping facts into observations with evidence references and proof counts. If newer information contradicts an older fact, the contradiction is resolved, the history is preserved, and the observation is updated rather than overwritten. Stale observations are flagged during reflect and verified against raw facts before use.
Memory Bank Configuration
Each memory bank carries a Mission (natural-language identity for the bank), Directives (hard rules the agent must follow), and Disposition traits (skepticism, literalism, and empathy on a 1-5 scale). These settings shape how reflect reasons and prioritizes knowledge without affecting retain or recall, so the same underlying memories can drive agents with different personalities.
LLM Wrapper and Native Integrations
Wrapping an existing LLM client adds persistent memory in two lines: wrap_openai() or wrap_anthropic() intercepts calls, recalls relevant memories before the request, and retains the conversation after it. For agent frameworks, 60+ integrations cover LangGraph, LlamaIndex, CrewAI, Pydantic AI, OpenAI Agents SDK, and more. Coding agent memory (per-repo banks from git history) supports Claude Code, Cursor, Codex CLI, and others.
Strengths and trade-offs#
Strengths
- MIT license with self-hosting on your own infrastructureThe server is MIT licensed and runs on your infrastructure with a single Docker command, with no per-seat fees and no per-query billing. Memory data stays on your servers and never routes through a third-party cloud. Compared to Mem0 and Zep's managed API tiers, self-hosting Hindsight gives you full ownership of the retention pipeline.
- State-of-the-art benchmark performanceHindsight reports the highest published accuracy on LongMemEval, a benchmark covering conversational AI memory scenarios. The results have been independently reproduced by researchers at Virginia Tech's Sanghani Center for AI and Data Analytics and The Washington Post; live per-model accuracy, latency, and cost figures are published at benchmarks.hindsight.vectorize.io.
- Multiple deployment paths, including embedded and KubernetesDocker, bare-metal pip install, Helm for Kubernetes, and a Python embedded mode (no server process needed) give teams flexibility to match their infrastructure. The embedded mode suits local development or lightweight tasks; the Helm chart handles production Kubernetes deployments with full feature parity.
- Four-arm retrieval handles query types vector search missesThe BM25 keyword arm finds exact names and technical terms that semantic search ranks poorly. The temporal arm filters by date range, handling queries like 'What happened in June?' that return noise from vector search alone. The entity graph arm connects related entities for indirect lookups. All four arms run in parallel and are fused before ranking.
Trade-offs
- -Retain and reflect require an external LLM API keyThe retain operation uses an LLM to extract entities, facts, and relationships from raw content. Reflect uses an LLM to reason over memories and generate answers. Running Hindsight depends on a working LLM provider connection (OpenAI, Anthropic, a local Ollama instance, or one of 25+ supported providers). Fully air-gapped deployments or budget-sensitive setups should factor in LLM inference costs for each retain call.
- -193 open GitHub issues at the time of reviewWith 193 open issues as of the research date, Hindsight is an actively developed project with known bugs and feature gaps. Teams using it in production should test against their specific agent workflows before committing; some edge cases in conflict resolution and temporal reasoning may not yet be fully handled.
- -Observation consolidation runs asynchronouslyWhen memories are retained, the Hindsight Worker consolidates facts into observations in a background process. During reflect, if new memories have arrived but consolidation has not yet completed, observations are flagged as stale and raw facts are checked first. Builds requiring low-latency reflect responses after high-frequency retain calls should account for this consolidation delay.
hindsight vs alternatives#
Hindsight vs Mem0
Both tools provide persistent memory APIs for AI agents, but they differ on deployment model and retrieval depth. Mem0 is a proprietary managed API; data stays on Mem0's cloud infrastructure and billing is usage-based. Hindsight is MIT licensed and fully self-hosted, with no per-query fees.
| Feature | Hindsight | Mem0 |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (Docker, pip, Helm) | No |
| Retrieval strategies | 4 parallel arms | Vector/semantic |
| Observation consolidation | Automatic with conflict resolution | Limited |
| Pricing | Free self-hosted; usage-based cloud | Usage-based API only |
Hindsight is the better choice when you need data ownership, full infrastructure control, or multi-strategy retrieval covering temporal and entity-graph queries. Mem0's managed API fits teams that want zero infrastructure overhead and are comfortable keeping memory data on a third-party cloud.
Hindsight vs Zep
Zep is a memory layer for AI assistants focused on conversation history and facts, primarily as a managed cloud service. Hindsight differs by offering full self-hosting under an MIT license, a four-tier memory hierarchy, and automated observation consolidation with conflict resolution.
| Feature | Hindsight | Zep |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes | Limited |
| Memory model | Facts, experiences, observations, mental models | Conversation history + facts |
| Retrieval | 4-arm TEMPR (semantic, keyword, graph, temporal) | Primarily vector |
| LLM-driven operations | Retain, reflect | Partial |
Hindsight is the stronger option for production agents that need to reason across sessions, consolidate conflicting information, and run on internal infrastructure. Zep suits simpler use cases where conversation history retrieval is enough and managed infrastructure is a priority.
Quick start#
Self-hosting uses a Docker container; pass your LLM API key at startup.
```bash
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
```What it's built on#
- Languages
- JavaScriptPythonRustTypeScript
- Frameworks
- Next.jsReact
FAQ#
Is Hindsight free to use?
The self-hosted version is MIT licensed and free to run on your own infrastructure. Hindsight Cloud, the managed hosted option, offers usage-based billing with free starting credits. For development and testing, the self-hosted Docker path is the quickest option and has no cost.
How does Hindsight differ from a standard vector database?
A vector database stores embeddings and retrieves by semantic similarity. Hindsight adds three more retrieval arms (keyword/BM25, entity graph, and temporal range), a memory hierarchy that consolidates facts into evidence-backed observations, and a reflect operation that reasons over stored memories using an LLM. It is designed as an agent memory system, not a general-purpose database.
Can I use Hindsight with my existing LLM setup?
Yes. The LLM Wrapper (wrap_openai or wrap_anthropic) adds memory to existing clients in two lines. Hindsight itself supports 25+ LLM providers via the HINDSIGHT_API_LLM_PROVIDER environment variable, including OpenAI, Anthropic, Gemini, local Ollama models, and GitHub Copilot subscriptions. No API key is needed when using an existing Copilot, ChatGPT Plus, or Claude Pro subscription.
How do I deploy Hindsight?
The quickest path is Docker: one docker run command starts the server with the REST API on port 8888 and a management UI on port 9999. Alternatively, pip install hindsight-api covers bare-metal installs, helm install handles Kubernetes, and pip install hindsight-all provides a Python embedded mode with no separate server process.
What is the difference between recall and reflect?
recall searches memory banks and returns relevant stored memories without LLM inference. reflect runs an agent reasoning loop that checks mental models, observations, and raw facts in priority order, then uses an LLM to synthesize an answer shaped by the bank's Mission, Directives, and Disposition settings. Use recall when you need fast memory lookup; use reflect when the agent needs to reason through a question.
Similar open-source tools#
ai-memory
Persist AI agent context across sessions and tool switches
mex
Persistent memory and code graph for AI coding agents
claude-mem
Stop re-explaining your codebase to every new agent session
cli
Official Lark/Feishu CLI with 200+ commands and AI Agent Skills
LibreChat
One self-hosted interface for every AI model you use
FckSignups
Open-source tools that work instantly, no signup required