Hindsight
A memory layer that helps agents retain, retrieve, and reflect on information over time.
- Source repo
- vectorize-io/hindsight
- Stars
- ★ 59k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 46/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A customer-support chatbot stores a user's conversations, tool calls, and metadata, then retrieves only that user's relevant memories in a later session.
- Not a fit if
- Teams that need fully offline operation with no LLM provider
- Teams unwilling to send conversation data to an external LLM or cloud
- Simple workflows where long-term memory is overkill
- Source review
- 46/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Hindsight is an agent-memory system for conversational and autonomous task agents that aims to support learning from prior information and experiences, not merely chat-history recall. It organizes data into memory banks and describes three memory types: world facts, experiences, and mental models formed through reflection. A server exposes Retain, Recall, and Reflect operations, with Python, Node.js/TypeScript, REST API, and CLI integration paths. Its Docker deployment exposes an API on port 8888 and a UI on port 9999; the repository also documents external PostgreSQL, Oracle AI Database, and embedded Python use through hindsight-all. It fits teams that need durable, scoped memory for an existing agent and want to retrieve or analyze it in later interactions.
A caller submits text with client.retain(bank_id, content), optionally including context, timestamp, and metadata. Retain uses an LLM to extract key facts, temporal data, entities, and relationships, then normalizes them into canonical entities, time series, search indexes, and metadata across world-fact or experience pathways. client.recall(bank_id, query) runs semantic vector search, BM25 keyword matching, entity/temporal/causal graph retrieval, and time-range filtering in parallel; it merges results with reciprocal rank fusion, reranks them with a cross-encoder model, and trims output to a token limit. client.reflect(bank_id, query) analyzes existing memories and experiences to produce observations, insights, or a response to the query. Applications can use hindsight-client, @vectorize-io/hindsight-client, or direct HTTP integration.
- A customer-support chatbot stores a user's conversations, tool calls, and metadata, then retrieves only that user's relevant memories in a later session.
- An AI project manager retains project events and uses Reflect to identify risks that need mitigation.
- A sales agent retains outreach experiences and outcomes, then reflects on why some messages received replies.
- A support agent accumulates customer questions and interactions, then identifies documentation gaps through reflection.
- A team adds retain, recall, and reflect calls to an existing Python or Node.js agent instead of building multi-strategy memory retrieval itself.
How do you install or deploy this agent?
Docker deployment requires an LLM-provider key. For OpenAI:
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:latestThe API is then available at http://localhost:8888 and the UI at http://localhost:9999. HINDSIGHT_API_LLM_PROVIDER can select openai, anthropic, gemini, groq, ollama, lmstudio, minimax, or atlas. Install the Python client with pip install hindsight-client -U, or the Node.js client with npm install @vectorize-io/hindsight-client. For embedded Python operation without a separate server, install hindsight-all -U; Intel x86_64 Macs should use hindsight-all-slim.
How do you use this agent?
First Python invocation:
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")
results = client.recall(bank_id="my-bank", query="What does Alice do?")
answer = client.reflect(bank_id="my-bank", query="Tell me about Alice")In Node.js, create new HindsightClient({ baseUrl: "http://localhost:8888" }), then call await client.retain("my-bank", "Alice loves hiking in Yosemite") and await client.recall("my-bank", "What does Alice like?"). Use the same bank_id to keep related memories in one memory bank.
What are this agent's strengths and limitations?
- Recall explicitly combines four parallel retrieval methods—semantic, BM25 keyword, graph, and temporal—instead of relying on vector similarity alone.
- Retain extracts and normalizes facts, entities, relationships, and temporal data so those representations can be reused by Recall and Reflect.
- The documented delivery options include a Docker service, embedded Python execution, Python and Node.js clients, REST API, and CLI.
- Memory banks and metadata filtering provide a documented mechanism for scoping memories, including per-user memory use cases.
- Retention and reflection require configuring an LLM provider and credentials; the supplied material lists providers but does not specify model pricing, quotas, or failure behavior.
- Embedded installation has a documented Intel x86_64 Mac caveat: it requires hindsight-all-slim.
- The README does not provide concrete configuration for authentication, authorization, backups, retention, or multi-tenant security boundaries, so these need validation before production adoption.
- Benchmark results are reported by the repository; it notes that other vendor scores in its comparison are self-reported, so retrieval quality should be tested against the adopter's own workload.
How does this agent compare with similar options?
The README positions Hindsight against memory approaches based only on RAG or knowledge graphs. Its documented recall path combines vector, keyword, graph, and temporal retrieval, while retention creates entity, relationship, and time-series representations. The supplied material does not provide a reproducible migration procedure or a feature-by-feature comparison with a named product.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Hindsight This agent | 46 · Major gaps | Self-hosted serviceFreemium | ★ 59k | today | Python | OpenAI API · Claude API |
| Memanto | 50 · Major gaps | CLIFreemium | ★ 2.4k | 6d ago | Python | Codex · Claude Code |
| Honcho Memory Infrastructure | 44 · Major gaps | Library / SDKFreemium | ★ 8k | today | Python | Claude Code · OpenAI API · Claude API |
| Mem0 Memory Layer | 52 · Major gaps | Library / SDKFreemium | ★ 68k | 2d ago | Python | ChatGPT · Codex · Claude Code · Claude.ai · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README provides Docker and embedded deployment configuration examples, but does not explicitly mention least privilege principles; user confirmation mechanism is not mentioned; data flow transparency partially describes retain/recall/reflect operations but does not explain how data is processed or stored; sensitive data handling is not specifically discussed; dependency security: package.json has overrides to fix known vulnerabilities, but no dependency audit report is provided; external effects: Docker command exposes ports and persists data, but network exposure risks are not explained; rollback mechanism is not mentioned; source attribution: README mentions built by Vectorize.io, but publisher is unverified. Deductions: lack of least privilege, user confirmation, rollback, and insufficient description of data flow and sensitive data handling.
Evidence shows: README and test files are consistent in describing API and functionality, but no complete error handling documentation is provided; dependency availability: multiple installation methods (Docker, pip, npm) are provided, but availability guarantees are not stated; failure messages: tests check error cases, but no user-friendly error message guidelines are provided. Deductions: incomplete error handling documentation and unclear dependency availability.
Evidence shows: README clearly defines target audience (AI agent developers) and multiple use cases (e.g., personalized chatbots, AI employees), and provides multiple deployment methods (Docker, embedded, client), but does not clearly define capability boundaries (e.g., supported models, data scale limits); trigger precision: describes retain/recall/reflect triggers but does not provide precise trigger rules; environment fit: provides platform support matrix but does not explain all environment variables. Deductions: insufficient description of capability boundaries and trigger precision.
Evidence shows: README has clear structure, provides installation instructions, example code, architecture description, and resource links, but does not provide FAQ or known limitations; naming stability: API names are consistent in documentation, but version compatibility is not stated; license is MIT, but no changelog is provided; maintenance responsibility: README mentions contributing guide, but maintainers are not clearly identified. Deductions: missing FAQ, known limitations, changelog, and maintainer information.
Evidence shows: README provides clear API examples and output formats, but does not provide output quality evaluation; marginal value: claims superiority over RAG and knowledge graphs, but no detailed comparison is provided; cost-benefit: no performance benchmarks or cost analysis are provided. Deductions: lack of output quality evaluation and cost-benefit analysis.
Evidence shows: README claims SOTA on LongMemEval and mentions independent reproduction, but does not provide specific data or reproduction steps; cross-source corroboration: mentions reproduction by Virginia Tech and Washington Post, but no links are provided; fact-inference separation: README mixes performance claims with architecture description without clear distinction. Deductions: performance claims lack verifiable data and reproduction details.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity is unverified; treat security and reliability claims with caution.
- Performance claims (e.g., LongMemEval SOTA) in README lack verifiable data and reproduction steps; do not rely solely on them.
- Docker deployment exposes ports and persists data; pay attention to network security and data protection.
- Dependency security relies only on overrides to fix known vulnerabilities; no complete dependency audit report is provided.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * docs: changelog and blog post for v1.1.0 by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5935 * docs(blog): ChatGPT sign-in recording in the v1.1.0 post by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5939 * fix(parsers): strip UTF-8 byte-order mark in markitdown text files by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5949 * fix(embeddings): don't fail the call when the provider omits prompt_tokens by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5951 …View on GitHub ↗ -
Release notes excerpt
What's Changed * docs: v1.0.0 changelog, Memlake launch post, and version-1.0 docs snapshot by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5550 * fix(client): stop the export poll loop from overrunning its timeout on Windows by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5568 * feat/webhook event delivery ids by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5576 * feat(control-plane): identify dataplane requests with its own User-Agent by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5536 …View on GitHub ↗ -
Release notes excerpt
What's Changed * fix(docs): overview hero reaches the window edges on wide screens by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5440 * docs: changelog and blog post for v0.10.3 by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5435 * docs: fix the home page link preview by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5441 * docs(blog): plain post titles with a description subtitle and byline row by @nicoloboschi in https://github.com/vectorize-io/hindsight/pull/5460 …View on GitHub ↗