Deploy Hindsight

Deploy and Host Hindsight on Railway

Hindsight is an open-source agent memory platform from Vectorize that gives AI agents durable, long-term memory instead of a short context window. Where a plain vector store only recalls past conversation snippets, Hindsight extracts facts, tracks entities and time, and forms "mental models" so an agent actually learns from what it has seen. It exposes three operations — Retain, Recall and Reflect — over a REST API, an MCP endpoint and Python/Node SDKs, and it has posted state-of-the-art scores on the LongMemEval benchmark. Teams use it to personalise chatbots, support agents, and autonomous "AI employees" that carry knowledge across sessions.

Deploy Hindsight on Railway and the full production topology is wired up in one click: the Hindsight API, a dedicated background worker, the Control Plane web UI, and a PostgreSQL database with pgvector. The API stores and retrieves memories, the worker handles extraction and consolidation off a Postgres-backed queue, and the Control Plane lets you explore memory banks, run recall queries and inspect the knowledge graph. It ships ready to self-host Hindsight with API-key authentication switched on, so nothing is left open.

Getting Started with Hindsight on Railway

After you deploy, Railway gives each public service its own URL. Open the Control Plane URL first — it shows a login screen. Sign in with the value of HINDSIGHT_CP_ACCESS_KEY, set automatically in the template variables. Once inside, create a memory bank from the dropdown at the top, then use the Recall page to run a query and see results ranked by semantic, keyword and reranker scores.

To use Hindsight from your own agent, point an SDK or HTTP client at the API URL and send the key as a bearer token. This stores a memory and reads it back with curl:

curl -X POST "$API_URL/v1/default/banks/my-bank/memories" \
  -H "Authorization: Bearer $HINDSIGHT_API_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"content":"Ada works at Railway and loves hiking."}]}'

curl -X POST "$API_URL/v1/default/banks/my-bank/memories/recall" \
  -H "Authorization: Bearer $HINDSIGHT_API_TENANT_API_KEY" \
  -H "Content-Type: application/json" -d '{"query":"Where does Ada work?"}'

A 200 with your memory in the recall results confirms it works end to end.

About Hosting Hindsight

Hindsight is a memory engine that sits between your agent and its language model. Retain extracts structured facts, resolves entities and builds temporal, semantic and causal links; Recall fuses four strategies (semantic vectors, BM25 keyword, graph traversal and time filtering) with a cross-encoder reranker; Reflect analyses stored memories to form new observations and mental models. All state lives in PostgreSQL, so the API and worker stay stateless and scale horizontally.

Key features:

• Retain / Recall / Reflect API with Python, Node.js, CLI and MCP clients
• Biomimetic memory model: world facts, experiences and learned mental models
• Hybrid retrieval — semantic + keyword + graph + temporal, with reranking
• Multi-provider LLM support (OpenAI, Anthropic, Gemini, Groq, Ollama and more)
• Bundled local embedding and reranking models — no external ML services required
• Control Plane UI to browse banks, entities, documents and recall traces

This template runs four Railway services. Hindsight API serves the public REST/MCP endpoints. Hindsight Worker runs the same image with the hindsight-worker command and processes retain, consolidation and maintenance jobs from a Postgres task queue. Hindsight Control Plane is the dashboard, talking to the API over the private network. PostgreSQL with pgvector stores every memory, embedding and link; its schema and extensions are created automatically on first boot.

Why Deploy Hindsight on Railway

Railway makes self-hosting the full Hindsight stack straightforward:

• One-click deploy of API, worker, Control Plane and PostgreSQL together
• Private networking between services with no manual configuration
• Automatic HTTPS domains for the API and dashboard
• Generated secrets and API-key auth enabled out of the box
• Vertical and horizontal scaling as your memory workload grows

Common Use Cases

• Give a customer-support agent memory of every past ticket and preference
• Personalise a chatbot with per-user facts recalled across sessions
• Let an autonomous agent learn workflows and avoid repeating mistakes

Dependencies for Hindsight

• Hindsight API / Worker — ghcr.io/vectorize-io/hindsight-api:0.9.1 (the full image, bundling local embedding and reranker models)
• Hindsight Control Plane — ghcr.io/vectorize-io/hindsight-control-plane:0.9.1
• PostgreSQL 18 with the pgvector extension — the single source of truth for all memory data

Environment Variables Reference

Deployment Dependencies

• Source images: ghcr.io/vectorize-io/hindsight-api and hindsight-control-plane
• GitHub repository: https://github.com/vectorize-io/hindsight
• Documentation: https://hindsight.vectorize.io

Hardware Requirements for Self-Hosting Hindsight

The full image loads a local embedder and cross-encoder reranker into memory, so give the API and worker at least 2 GB RAM each. The slim image variant offloads those to external providers and needs far less.

Self-Hosting Hindsight

On Railway, click Deploy, wait for the four services to go green, then open the Control Plane URL and sign in. To run Hindsight locally instead, the quickest path is the all-in-one Docker image with an embedded database:

docker run -it --pull always -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

For production, run the API against an external PostgreSQL with pgvector, as this template does — set HINDSIGHT_API_DATABASE_URL, enable API-key auth, and add worker processes as throughput grows:

HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/hindsight \
HINDSIGHT_API_WORKER_ENABLED=false \
hindsight-api

hindsight-worker --worker-id worker-1

How Much Does Hindsight Cost to Self-Host?

Hindsight is free and open source under the MIT license, so there is no software fee to self-host it. On Railway you pay only for the compute and storage the four services use. Vectorize also offers a managed Hindsight Cloud if you would rather not run it yourself. Note that fact extraction and reflect call an external LLM, so those features add your provider's per-token cost.

FAQ

What is Hindsight? Hindsight is an open-source agent memory system that stores, links and retrieves what an AI agent learns, so it can recall facts and improve over time rather than starting fresh each session.

What does this Railway template deploy? It deploys four services: the Hindsight API, a dedicated background worker, the Control Plane web UI, and a PostgreSQL database with pgvector. Authentication and secrets are configured automatically.

Why does the template include PostgreSQL and pgvector? Hindsight keeps all memories, embeddings and graph links in PostgreSQL and uses the pgvector extension for semantic similarity search. The required extensions are installed automatically on first boot.

Do I need an LLM API key to run Hindsight on Railway? No. The template ships with HINDSIGHT_API_LLM_PROVIDER=none, running Hindsight as a semantic store on its bundled local models. Set a provider and HINDSIGHT_API_LLM_API_KEY to enable fact extraction, reflect and consolidation.

How do I enable API key authentication in self-hosted Hindsight? The template already enables it: the API requires the HINDSIGHT_API_TENANT_API_KEY bearer token on every REST and MCP request. Requests without a valid key get a 401.

Can I scale Hindsight for high throughput? Yes. The API and worker are stateless, so you can raise replica counts or add more worker services; each worker needs a stable HINDSIGHT_API_WORKER_ID, which the template sets for you.