Annotated mirror · Vectorize · MIT license
Memory for agents that learns
The agent stores what it lived through, searches four ways and merges what it learned into beliefs with evidence. It runs on your machine.
The agent stores what it lived through, searches four ways and merges what it learned into beliefs with evidence. It runs on your machine.
Hindsight is a long-term memory system for AI agents, created by Vectorize and open source under the MIT license. It is for people who build agents, bots or assistants that need to remember conversations and decisions from one session to the next. Instead of only storing the history, it extracts facts, merges the repeated ones and forms beliefs with evidence, so the agent learns over time. To use it, you need Python 3.11 or Docker and a language model, which can be your Claude or Codex subscription or a local model.
You only call three things: retain, recall and reflect. The rest (facts, entities, dates, consolidation) happens underneath.
retain extracts facts with a language model; recall searches by meaning, exact word, entity graph and time period; reflect analyzes what is stored and answers questions that need reasoning.
Similar facts become observations, with a citation of the evidence and a count of confirmations. Mental models are fixed questions ("what are the user's preferences?") whose answers it rewrites on its own as it learns.
Each bank is an isolated memory: one per user, client, agent or project, with no leakage between them. Optionally it blocks keys and personal data before storing.
Every retain goes through a language model. Afterwards, in the background, the bank consolidates itself.
"The stove gets hot." What is true about the agent's world.
"I touched the stove and got burned." What the agent itself lived through.
Beliefs consolidated from many facts, refined (not overwritten) when new evidence arrives.
Knowledge pages the bank writes about itself and keeps up to date. Reading one is just a database query, with no model call.
Four-way search. recall runs semantic search (vectors), exact-word search (BM25), graph search (entities, time, cause) and time-period search at the same time, merges the results and reranks them with a reranking model before fitting the token limit.
The database is built in (PostgreSQL pg0) and the vectors are computed locally. The only external resource is the language model.
Embedded mode installs with pip or runs without installing through uvx.
python3 --version uvx hindsight-embed --help
No API key needed: claude-code (Claude Pro/Max subscription), openai-codex (ChatGPT Plus/Pro) or local ollama. It also accepts more than 25 providers by key.
claude auth status # already logged in?
On the first run it downloads the vector and reranking models (1 to 3 minutes). On a shared server, run it with a memory cap.
systemd-run --user --scope -p MemoryMax=8G \
hindsight-embed daemon startLocal path, no server and no API key, using the Claude subscription. Commands taken from the hindsight-embed README and the models documentation.
A background process starts on its own on port 8888 and shuts down after 5 idle minutes.
pip install hindsight-embed # or: uvx hindsight-embed ...
The default vector model (bge-small-en) is English only. For Portuguese, Spanish and other languages, the documentation itself recommends BAAI/bge-m3.
hindsight-embed configure \ --env HINDSIGHT_API_LLM_PROVIDER=claude-code \ --env HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-m3
The first argument is the bank. Use one bank per project, client or agent.
hindsight-embed memory retain default "The user prefers short answers" hindsight-embed memory recall default "How does the user like answers?"
For questions that need analysis, not just search.
hindsight-embed memory reflect default "What patterns show up in the user's preferences?" hindsight-embed bank list # existing banks hindsight-embed daemon logs -n 100 # what the process did
The plugin searches memories on every prompt and stores the conversation after each reply, through hooks. It also brings MCP tools for knowledge pages.
claude plugin marketplace add vectorize-io/hindsight claude plugin install hindsight-memory export HINDSIGHT_LLM_PROVIDER=claude-code
Three hooks: it warms up the server on open, searches memories on every request and stores when it finishes. Requires Codex 0.116 or newer. Read the script before running it.
curl -fsSL https://hindsight.vectorize.io/get-codex -o get-codex.sh less get-codex.sh && bash get-codex.sh
Python client (there are also Node.js, Go and a CLI) pointing at the local server.
from hindsight_client import Hindsight client = Hindsight(base_url="http://localhost:8888") client.retain(bank_id="cliente-42", content="Asked for a quote for 3 rooms") client.recall(bank_id="cliente-42", query="What did the client ask for?") client.reflect(bank_id="cliente-42", query="What is the next step with them?")
Before turning it on everywhere. Every retain is a model call: storing every reply of every session uses up your subscription quota. The documentation warns that the claude-code provider is for personal, local use (it uses the official Claude Agent SDK with your login); for a team or production, they recommend an API key.
Analysis done on 10/15/2026 by reading the code. None of this has been installed yet: it is the map of the adaptation.
| Today | Current limit | What Hindsight adds |
|---|---|---|
| Memory in files (MEMORY.md + one file per fact) | Manual; the index grows, repeated and stale facts pile up | Consolidates on its own, refines beliefs with new evidence, understands dates |
| Lessons, FALHAS.md and LIMITES.md | They only grow; nobody extracts the pattern | reflect extracts the pattern from repeated errors |
| Search in session history | Exact word only | Search by meaning, entity and time period |
| Current Claude Code memory plugin | Sometimes fails to connect | Ready-made plugin for Claude Code and for Codex |
| Support bots and kits | No per-client memory | One isolated bank per client, with sensitive-data blocking |
| The "second brain" topic | Conceptual | Real foundation for a guide, course and demo |
In order; each stage only starts if the previous one proves its value.
recall/reflect with the current search on questions like "which video mistakes do I repeat?". Measure quota use per retain.