Skip to content
Get packs

Guide · Open source

How to use Hindsight: start a server, store and recall memories

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hindsight is an open-source agent memory system, released under the MIT licence, that gives AI agents a place to store and search what they have learned. The project says most memory systems focus on recalling conversation history, while Hindsight is aimed at agents that learn over time. This guide shows how to start a Hindsight server with Docker, connect a client, and use its retain, recall and reflect operations.

Hindsightvectorize-io/hindsight · ★ 57.9k · MIT

Quick start

  1. 1Check prerequisites. Make sure Docker is installed and you have an LLM API key or a local provider such as Ollama.
  2. 2Export your API key. Set OPENAI_API_KEY in your shell so the container can pass it to Hindsight.
  3. 3Start the container. Run the docker run command from the README, which maps ports 8888 and 9999.
  4. 4Install the Python client. Run pip install hindsight-client -U.
  5. 5Store a memory. Call retain with a bank_id and the content you want remembered.
  6. 6Search and reflect. Call recall to search the bank, then reflect to generate a response from it.

What do you need before you install Hindsight?

You need Docker and an LLM API key, or a local model provider such as Ollama. Hindsight works with 25+ LLM providers, including hosted ones such as OpenAI and Anthropic, and fully local ones such as Ollama, LM Studio and llama.cpp.

Hindsight is a larger system than a simple chat history buffer. If you only need to keep a short list of past messages, it is more than that requires.

  • Docker
  • An LLM API key, or a local model provider such as Ollama

How do you start the Hindsight server with Docker?

Export your API key, then run the container. The API listens on port 8888 and the UI on port 9999. The data is kept in a Docker volume named hindsight-data.

The README also lists options for external PostgreSQL with Docker Compose, Bare metal with pip, Kubernetes with Helm, and Hindsight Cloud for a managed option.

  • API: http://localhost:8888
  • UI: http://localhost: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

How do you connect the Python client?

Install the client with pip, then point it at your local server. The README shows three core calls: retain stores information, recall searches memories, and reflect generates a response that takes the memory into account.

Node.js, Go and CLI clients are also available, and the README links to a REST API reference.

pip install hindsight-client -U 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")

What do retain, recall and reflect do?

Retain saves information to a memory bank. Recall searches those memories for a query. Reflect generates a response to a query using the stored memories, as shown in the README's Python example.

Memories are grouped into banks. The example uses a bank called my-bank.

  • retain: store information in a bank
  • recall: search memories in a bank
  • reflect: generate a response from memory

Can you try Hindsight without running a server?

The README describes an embedded option for Python. Install the hindsight-all package, and the Python code can start a HindsightServer in the same process, with no separate server needed. Intel Mac users should install hindsight-all-slim instead.

Hindsight Cloud is the other route. You point any client at the hosted API with your API key and skip the deployment.

pip install hindsight-all -U

What people use it for

  • Giving an AI agent memory of a user across separate sessions
  • Running a self-hosted memory server for a team with a choice of LLM providers
  • Trying a memory layer quickly through Docker
  • Using Hindsight Cloud instead of running your own infrastructure

Frequently asked questions

Is Hindsight free?

Hindsight is released under the MIT licence, which is stated in the project's licence badge. The README also describes Hindsight Cloud as usage-based billing with free credits to start, with no fixed monthly or per-seat fee.

What do I need to install Hindsight?

The README lists Docker and an LLM API key, or a local model provider such as Ollama, as prerequisites. The Docker method is the quickest route.

How do I install Hindsight with Docker?

Export your API key and run the docker run command shown in the README, which pulls ghcr.io/vectorize-io/hindsight:latest and maps ports 8888 and 9999. The API will be at localhost:8888 and the UI at localhost:9999.

Which languages can I use to connect to Hindsight?

The README lists Python, Node.js/TypeScript, Go and a CLI client, plus a REST API reference. The Python client is installed with pip install hindsight-client.

What are the alternatives to Hindsight?

The project lists Mem0, Letta, Zep and LangChain memory as comparable projects. This guide does not compare their features or performance.

Are Hindsight's benchmark results verified?

The README says the Hindsight benchmark results were independently reproduced by research collaborators at Virginia Tech's Sanghani Center and The Washington Post. It also says other scores are self-reported by software vendors.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hindsight suits developers building agents that need memory across sessions, especially if they want a self-hosted server or a managed Cloud option. If you only need a simple chat history buffer, or you want a no-code app, pick a lighter tool or a different product.

Install options & downloads