Hindsight: an agent memory server where every retain, recall and reflect call runs through an LLM you configure

The server needs an LLM configured before it will start, so memory has a model bill

The Docker quick start sets an LLM key before anything else, passing it as HINDSIGHT_API_LLM_API_KEY, and the .env.example file marks LLM configuration as required, with a provider, a key and a model whose example value is gpt-4o-mini. The server exposes an API on port 8888 and a UI on port 9999:

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 consequence is that the memory system is not a passive store. It uses a language model, so you pay for or host that model, and the quality of what is retained depends on it. Choose the provider before you design anything else, and keep the data volume mount so the memory survives a container restart.

Over 25 providers are supported, including local runtimes and existing subscriptions

The provider is selected with HINDSIGHT_API_LLM_PROVIDER. Hosted options listed include openai, anthropic, gemini, groq, bedrock, vertexai, minimax and deepseek. Fully local options are ollama, lmstudio and llamacpp, any OpenAI-compatible endpoint works, and litellm gateways reach the rest. Four providers use existing subscriptions and need no API key: openai-codex for ChatGPT Plus or Pro, claude-code for Claude Pro or Max, cursor and github-copilot.

The .env.example also describes a separate vision slot, used only for retain chunks that carry an inline attachment, so a bank that ingests the occasional screenshot need not run a vision model on all its text. It also describes a reasoning effort setting: when set, the value is sent as given, and unset, no reasoning parameter is sent at all.

Storage is embedded by default, with external PostgreSQL and Oracle as the production routes

The Docker command mounts a volume at /home/hindsight/.pg0, which holds the default data. For a production-style setup, a compose file under docker/docker-compose uses an external PostgreSQL, and the instructions set a database password before running docker compose up:

export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up

The README adds that Oracle AI Database is also supported for enterprise deployments with full feature parity. Other install routes are bare metal and Kubernetes. The practical rule is to move off the default volume when memory becomes valuable, because backups and upgrades are then handled by a database you already operate.

Bare metal and Helm installs differ in how the key and database are supplied

Bare metal is a pip package and a command:

pip install hindsight-api
export HINDSIGHT_API_LLM_API_KEY=sk-xxx

hindsight-api

On Kubernetes the Helm chart is installed from an OCI registry with the LLM provider and key as chart values and a flag to enable the bundled PostgreSQL:

helm install hindsight oci://ghcr.io/vectorize-io/charts/hindsight \
  --set api.llm.provider=openai \
  --set api.llm.apiKey=sk-xxx \
  --set postgresql.enabled=true

Passing the key with --set puts it in your shell history and in the release values, so a secrets mechanism is the safer route for anything beyond a trial.

Retain, recall and reflect are the three operations, shown in the Python client

After the server runs, a client connects to the base URL and calls three operations:

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Retain: Store information
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")

Every call names a bank, which is the unit that separates one agent's or user's memory from another's. Clients exist for Python, Node.js and TypeScript, Go, and a CLI installed with a curl command. A Node example shows the same retain and recall calls with positional arguments.

The benchmark claim is strong, and the README says which scores were independently reproduced

Hindsight is described as the most accurate agent memory system ever tested according to benchmark performance, with state-of-the-art results on the LongMemEval benchmark. The reported figures are dated January 2026, and live results are said to be published on a separate benchmarks site.

The README is explicit about provenance. The Hindsight numbers were independently reproduced by research collaborators at the Virginia Tech Sanghani Center for Artificial Intelligence and Data Analytics and The Washington Post, while other scores are self-reported by software vendors. So the comparison is between a reproduced figure and unverified ones. The text also says Hindsight is used in production at Fortune 500 enterprises, which is a statement without named customers. Run your own recall tests before trusting either claim.

Core concepts include banks, observations and mental models, and their definitions live in the docs

The contents list of the README names the core concepts: memory types, the three operations of retain, recall and reflect, observations, mental models and knowledge pages, and memory banks. The project frames Hindsight as aimed at agents that learn, not just remember, and says it removes the shortcomings of RAG and knowledge graph techniques.

Observations and mental models are terms you will meet on the documentation site, and they are not explained in the README itself. The consequence for adopters is a learning curve beyond three function calls: before you design a schema for your agent's memory, read how banks isolate data and what reflect does differently from recall. The reflect call is described in the Python example as generating a disposition-aware response.

There are several ways to attach it to an agent, from a two-line wrapper to an MCP server

Under the heading for adding Hindsight to your agent, the README lists an LLM wrapper that takes two lines of code, a set of integrations, coding agent support and an MCP server. It also lists a Python embedded mode with no server required, and a section on running in production.

This range means the server in the quick start is one choice among several. If you want memory inside a single Python process during development, the embedded route avoids running Docker. If you work in Claude Code or Cursor, the MCP server and the documentation skill give those tools access. The choice affects where memory lives: an embedded process keeps it local to that process, while a server shares one memory across many clients.

The repository includes hindsight-embed, hindsight-extensions and hindsight-integrations directories, which correspond to these routes.

Hindsight Cloud removes the deployment, with usage-based billing and an SLA

The hosted option is Hindsight Cloud. The README describes managed infrastructure that scales automatically, a dashboard, backups, team collaboration and a 99.9% uptime SLA, with billing based on usage, free credits to start, and no fixed monthly or per-seat fee. You point any client at https://api.hindsight.vectorize.io with your API key and skip the deployment entirely. A pricing page compares self-hosted, Cloud and Enterprise.

The trade is data location. With Cloud, your memories live on the vendor's infrastructure, while the self-hosted options keep them in your own PostgreSQL or Oracle database. The README's phrase that billing is usage-based does not give a unit price, so check the pricing page before estimating cost for an agent that retains a lot of conversation.

v1.0.0 arrived on 2026-10-13, followed by v1.1.0 eight days later

The recent releases are v1.1.0 on 2026-10-21, v1.0.0 on 2026-10-13 and v0.10.3 on 2026-10-08, and the last push was on 2026-11-02. A 1.0 tag after a long 0.x series suggests an API settling, but it is under a month old, so pin the version you deploy and read the release notes.

The repository is a large workspace: hindsight-api, a slim API variant, hindsight-embed, a control plane, a CLI, clients, integrations, extensions, docs, cookbook, a Helm chart and system evaluation and test directories. Hindsight Cloud is the hosted option, with usage-based billing, free starting credits and a 99.9% uptime SLA. A documentation skill for coding agents installs with npx skills add pointing at this repository.

Editorial conclusion

Hindsight suits teams building agents that should accumulate and reuse knowledge across sessions and who can run a server plus an LLM provider for it. It is a poor fit if you want a no-dependency library with no model calls, or if you need independent confirmation of every benchmark claim. Before adopting it, choose your LLM provider and storage deliberately, keep the API port off the public internet, and test retain and recall on your own data.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vectorize-io/hindsight on GitHub