---
title: "Deploy Hindsight"
description: "Open-source long-term memory.Retain/Recall/Reflect memory API"
category: "AI/ML"
url: https://railway.com/deploy/hindsight-memory-api
---

# Deploy Hindsight

Open-source long-term memory.Retain/Recall/Reflect memory API

**[Deploy Hindsight on Railway](https://railway.com/template/hindsight-memory-api)**

- **Creator:** A3A
- **Category:** AI/ML
- **Total deploys:** 3

## Template content

### hindsight-api https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-favicon.png

- **Image:** ghcr.io/vectorize-io/hindsight-api:0.9.1
- **Health check:** /health
- **Public domain:** Yes

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### hindsight-control-plane https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-favicon.png

- **Image:** ghcr.io/vectorize-io/hindsight-control-plane:0.9.1
- **Health check:** /api/health
- **Public domain:** Yes

### hindsight-worker https://raw.githubusercontent.com/vectorize-io/hindsight/main/hindsight-favicon.png

- **Image:** ghcr.io/vectorize-io/hindsight-api:0.9.1
- **Start command:** `hindsight-worker`
- **Health check:** /health

## Documentation

![Hindsight logo](https://hindsight.vectorize.io/img/blog/fastest-growing-oss-ai-memory.png)

# 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.

![Hindsight Railway architecture](https://hindsight.vectorize.io/img/blog/fastest-growing-oss-ai-memory.png)

## 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.

![Hindsight memory bank table listing three stored world facts](https://res.cloudinary.com/rroe4rtk/image/upload/v1787073392/hindsight-memories-table.png)
![Hindsight recall analyzer returning ranked semantic search results](https://res.cloudinary.com/rroe4rtk/image/upload/v1787073398/hindsight-recall-ranked-results.png)
![Hindsight bank overview with memory constellation graph and stats](https://res.cloudinary.com/rroe4rtk/image/upload/v1787073433/hindsight-home-constellation.png)

## 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

| Variable | Service | Purpose |
|---|---|---|
| `HINDSIGHT_API_DATABASE_URL` | API, Worker | PostgreSQL connection string |
| `HINDSIGHT_API_LLM_PROVIDER` | API, Worker | LLM provider; `none` for a semantic-only store |
| `HINDSIGHT_API_LLM_API_KEY` | API, Worker | LLM key that unlocks fact extraction and reflect |
| `HINDSIGHT_API_TENANT_API_KEY` | API | Bearer key required on every REST/MCP request |
| `HINDSIGHT_CP_ACCESS_KEY` | Control Plane | Password for the dashboard login |
| `HINDSIGHT_CP_DATAPLANE_API_URL` | Control Plane | Private URL of the API service |

### Deployment Dependencies

- Source images: [ghcr.io/vectorize-io/hindsight-api](https://github.com/vectorize-io/hindsight/pkgs/container/hindsight-api) and [hindsight-control-plane](https://github.com/vectorize-io/hindsight/pkgs/container/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.

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM (API / Worker) | 1.5 GB each | 2 GB each |
| RAM (Control Plane) | 128 MB | 256 MB |
| RAM (PostgreSQL) | 512 MB | 1 GB+ |
| Storage | 1 GB | Grows with memory volume |
| Runtime | Docker (linux/amd64, arm64) | Docker |

## 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/hindsight-memory-api