Hindsight Setup: Give Your AI Agent Memory That Learns

Q: How do you add memory to an existing agent?

The lowest-effort path is the LLM wrapper. You install hindsight-litellm , wrap your existing OpenAI or Anthropic client with wrap_openai() or wrap_anthropic() , and pass a bank_id plus hindsight_api_url="http://localhost:8888" .

Hindsight is an open-source memory server for AI agents from Vectorize: instead of stuffing old chat logs back into a prompt, it extracts facts, entities and timestamps from everything an agent sees, consolidates them into beliefs over time, and hands back only what is relevant when the agent asks. It is the top Python repository on GitHub trending today with roughly 4,500 new stars, on top of about 37,000 total, and version 0.10.1 shipped on 21 September. A working local setup takes about fifteen minutes: one Docker command with an LLM key, a pip install for the client, and three API calls named retain, recall and reflect.

Hindsight runs as a server with a REST API on port 8888 and a web UI on port 9999, backed by PostgreSQL with pgvector, or an embedded Postgres called pg0 for development.
It needs an LLM for fact extraction, and supports more than 25 providers, including fully local Ollama, LM Studio and llama.cpp if you do not want to send data to a hosted model.
Recall runs four retrieval strategies in parallel (semantic, keyword, graph and temporal), then merges them with reciprocal rank fusion and a cross-encoder reranker.
The project claims state-of-the-art LongMemEval scores, and says Virginia Tech's Sanghani Center and The Washington Post independently reproduced them. Competitor numbers on its chart are self-reported.

The exact steps, start to finish

Check your prerequisites. You need Docker for the recommended route, or Python 3.11 or newer for the pip route. Node.js is only needed for the standalone web UI and the coding-agent integration.
```
$ docker --version
$ python --version
$ pip --version
$ node --version
```
Get an LLM key, or pick a local model. Hindsight calls an LLM every time it retains a memory. The quick start uses an OpenAI key, which you create at platform.openai.com/api-keys. To stay fully local instead, run Ollama and use the provider lines from Hindsight's models page.
```
# hosted: OpenAI
$ export OPENAI_API_KEY=sk-xxx
# or fully local: Ollama
$ export HINDSIGHT_API_LLM_PROVIDER=ollama
$ export HINDSIGHT_API_LLM_BASE_URL=http://localhost:11434/v1
$ export HINDSIGHT_API_LLM_MODEL=llama3
```

Start the server with Docker. This single container bundles the API, the web UI, the embedding and reranker models, and an embedded Postgres whose data lives in a named volume.

$ 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

Or start it without Docker on Windows. The pip package runs natively with the same embedded database. In Command Prompt:

pip install hindsight-api
set HINDSIGHT_API_LLM_PROVIDER=openai
set HINDSIGHT_API_LLM_API_KEY=sk-xxx
set HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
hindsight-api

Install the client. Python is shown here; the same README line also covers Node.js, Go and a CLI.
```
$ pip install hindsight-client -U
```

Store, search and reason over a memory. This is the payoff step. Save it as demo.py and run it against the server you started.

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

Open the web UI. With Docker it is already running at http://localhost:9999. On the pip route, start it separately and point it at your API:
```
$ npx @vectorize-io/hindsight-control-plane --api-url http://localhost:8888
```
Optional: give your coding agent project memory. One package wires Hindsight into Claude Code, Codex CLI, Cursor CLI and others that it detects.
```
$ npx @vectorize-io/hindsight-coding-agents install claude-code
```

Fig 1 Retain turns raw text into structured memories inside an isolated bank. Recall searches that bank four ways at once, and background consolidation slowly turns piles of facts into observations and mental models.

What is Hindsight and why is it trending?

Most agent memory today is retrieval over conversation history: chunk the transcript, embed it, pull back the nearest chunks. Hindsight's pitch is that this remembers but does not learn. It sorts incoming information into separate pathways, world facts ("the stove gets hot") and the agent's own experiences ("I touched the stove and it hurt"), and stores each as a mix of entities, relationships, time series and sparse plus dense vectors. A background process then consolidates related facts into observations, which keep their supporting quotes and a proof count, and get refined rather than overwritten when new evidence contradicts them.

On top of that sit mental models, standing answers to questions you define once ("What are this user's preferences?") that Hindsight rewrites in the background as the bank learns. Reading one is a plain database read with no LLM call, which is the practical win: an agent can start a session with a page of settled knowledge instead of rediscovering it. Knowledge pages are the same idea presented as a folder of markdown documents the bank writes about itself, searchable and exportable to disk.

The trending spike lines up with that release cycle and with the project's push into coding agents. The README now ships a one-line installer that builds a per-repository memory bank from git history and past sessions for Claude Code, Codex CLI, Cursor CLI, GitHub Copilot CLI and a dozen others. The research is published as an arXiv paper, and the project says it is already in production at Fortune 500 companies.

How do you install Hindsight on Linux, macOS and Windows?

Docker is the recommended route on every platform, and the checklist above uses it. Be aware of the image size before you pull: the full image is about 9 GB on x86 machines and 3.7 GB on ARM, because it bundles the local BGE embedding model and a MiniLM cross-encoder plus their PyTorch runtimes. A slim image of about 500 MB exists, but it expects you to supply external embedding and reranking providers such as OpenAI, Cohere or a Text Embeddings Inference server.

The pip package is the lighter option for a laptop, and the installation guide lists Windows on x86_64 as fully supported for Docker, bare metal and the embedded database. On Linux and Apple Silicon Macs the commands are the same as step 4 with export in place of set. Intel Macs are the exception: the full bundle's machine learning wheels do not exist for that platform, so the docs tell you to install hindsight-api-slim and pair it with hosted models or the in-process ONNX embedder.

For anything beyond a test, point Hindsight at a real PostgreSQL 14 or newer with pgvector enabled through HINDSIGHT_API_DATABASE_URL. The repository also ships a Compose file that runs Hindsight with an external Postgres:

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

If you would rather not run anything at all, Hindsight Cloud is the hosted option with usage-based billing and free starting credits, and clients simply point at https://api.hindsight.vectorize.io with an API key.

How do you add memory to an existing agent?

The lowest-effort path is the LLM wrapper. You install hindsight-litellm, wrap your existing OpenAI or Anthropic client with wrap_openai() or wrap_anthropic(), and pass a bank_id plus hindsight_api_url="http://localhost:8888". From then on Hindsight recalls relevant memories before each call and retains the conversation after it. One detail to catch: the wrapper defaults to Hindsight Cloud, so on a self-hosted setup you must pass the URL explicitly or your data goes to the hosted service.

Every server also exposes a Model Context Protocol endpoint per bank at http://localhost:8888/mcp/{bank_id}/, enabled by default, so any MCP client can use retain, recall and reflect as tools with no code. The project lists more than 60 framework integrations.

Approach	How it stores memory	Learns over time	Self-hostable
Hindsight	Facts, experiences, entities and time series in Postgres	Yes, via observations and mental models	Yes, MIT license
Plain RAG over chat logs	Embedded text chunks in a vector store	No, it only retrieves	Yes
Mem0	Extracted memories in vector and graph stores	Updates memories as facts change	Yes, open-source core
Zep	A temporal knowledge graph	Tracks how facts change over time	Graph engine is open source

What are the gotchas before you rely on it?

Cost and latency come first. Every retain is an LLM call that extracts facts and resolves entities, so a busy agent that retains every turn is also a busy LLM bill. A small local model keeps it free, but quality drops with model size. We ran step 4 on a Windows 10 laptop with pip and Alibaba's tiny qwen3:0.6b through Ollama: retain extracted the Alice fact correctly and recall found it again, but reflect confidently replied that the bank held no information about Alice. Use a tiny model to learn the API, and check the project's "Which model should I use?" page before judging the results.

Second, the embedding model is effectively permanent. The docs warn that once memories are stored you cannot change embedding dimensions without losing data, so choose your embeddings provider before you load anything you care about. Third, the embedded pg0 database is explicitly for development; production means a real Postgres with a vector extension. Fourth, in production set a stable HINDSIGHT_API_WORKER_ID, because the worker otherwise uses the container ID, which changes on every restart and can leave in-flight tasks parked under an identity nobody claims.

Finally, memory is a privacy surface. Banks are strictly isolated from each other, and there is an opt-in Memory Defense policy that scans every retain for secrets and personal data against 45 patterns and redacts or blocks matches. It is off by default, so turn it on for any bank that ingests user conversations or tool output.

What to watch

Independent benchmarks. The LongMemEval lead is the headline claim, and the live benchmark site now tracks accuracy, latency and cost per model. Watch whether rivals publish reproducible numbers against it.
Coding-agent memory. The per-repo installer is the feature most likely to reach everyday developers, and the one where stale or wrong memories would hurt most.

Our take

Hindsight is the most complete self-hostable take on agent memory we have set up, and the distinction it draws between remembering and learning is not just marketing: observations with evidence counts and background-refreshed mental models are a genuinely different design from bolting a vector store onto a chatbot. The price of that design is weight. A 9 GB container and an LLM call on every write is a lot of machinery for a hobby chatbot, and the README itself admits it may be overkill for simple n8n-style workflows. If you are building an agent that runs for weeks against the same users or the same codebase, start here, with a local model to learn it and a hosted one once extraction quality starts to matter. If you just need last week's chat history, plain retrieval is still fine.

Primary sources

Officialvectorize-io/hindsight repository and README
OfficialHindsight releases v0.10.1, published 21 September 2026
OfficialInstallation guide Docker, pip, Windows and image variants
OfficialModels and providers LLM, embedding and reranker configuration, including Ollama
ResearchHindsight paper on arXiv architecture and LongMemEval results
BenchmarkHindsight benchmarks live accuracy, latency and cost per model

Original analysis by GenZTech. Tool documentation: vectorize-io/hindsight on GitHub.