vectorize-io/hindsight

Hindsight: Agent Memory That Learns

Summary

Hindsight is a Python-based memory system for agents that need to learn across conversations and tasks, rather than only replay chat history. It organizes retained information into world facts, experiences, evidence-backed observations, and reusable mental models, then exposes it through retain, recall, and reflect operations. It can run as a service, an embedded Python component, or a managed service, with clients for Python, Node.js, Go, and a CLI.

What it is useful for

The clearest fit is a long-lived agent whose answers must reflect prior work. For example, an agent could retain “Alice got promoted to senior engineer,” recall it for “What does Alice do?”, and use reflect to answer broader questions such as “What should I know about Alice?” Memory banks isolate one user, agent, or project, with no cross-bank leakage.

Recall combines vector similarity, keyword matching, entity and temporal relationships, and time filtering. Reflect is the deeper synthesis path. The README gives concrete examples: an AI project manager can reflect on project risks, a sales agent can compare outreach outcomes, and a support agent can identify gaps in product documentation. For coding assistants, the documented package builds a per-repository bank from git history and prior sessions, injects project memory at startup, and maintains knowledge pages covering architecture, conventions, and in-progress work.

Hindsight may be overkill for simple workflows such as a basic n8n application. Its secret and PII scanning policy is also opt-in per bank. The README notes an Intel macOS caveat: embedded users should install hindsight-all-slim rather than hindsight-all.

How engineers can use it

The README recommends Docker for the server. With an OpenAI key, its documented command is:

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 on port 8888 and the UI on 9999. Because retain uses an LLM to extract facts, temporal data, entities, and relationships, configure an LLM provider before ingesting memories.

Install the Python client and use the three core operations:

pip install hindsight-client -U

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

For an existing OpenAI client, the documented hindsight-litellm wrapper can recall memories before a call and retain the conversation afterward. Use the SDK or REST API directly when engineers need explicit control over when storage and retrieval happen.