Hindsight

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.

1. 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.
2. An AI project manager retains project events and uses Reflect to identify risks that need mitigation.
3. A sales agent retains outreach experiences and outcomes, then reflects on why some messages received replies.
4. A support agent accumulates customer questions and interactions, then identifies documentation gaps through reflection.
5. A team adds retain, recall, and reflect calls to an existing Python or Node.js agent instead of building multi-strategy memory retrieval itself.

What are this agent's strengths and limitations?

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:latest

The 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.

How does this agent compare with similar options?

FAQ