---
title: "Deploy Hindsight v1 Agent Memory Server"
description: "Long-term memory API and dashboard for AI agents, on Postgres."
category: "AI/ML"
url: https://railway.com/deploy/hindsight-v1-agent-memory-server
---

# Deploy Hindsight v1 Agent Memory Server

Long-term memory API and dashboard for AI agents, on Postgres.

**[Deploy Hindsight v1 Agent Memory Server on Railway](https://railway.com/template/hindsight-v1-agent-memory-server)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/hindsight-v1-agent-memory-server/manifest.json

- **Creator:** bento
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### Hindsight Worker https://cdn.jsdelivr.net/gh/vectorize-io/hindsight@v1.0.0/hindsight-favicon.png

- **Image:** ghcr.io/vectorize-io/hindsight-api:1.0.0
- **Start command:** `/bin/sh -c 'case "$HINDSIGHT_API_LLM_PROVIDER" in ""|openai) if [ -z "$HINDSIGHT_API_LLM_API_KEY" ] && [ -z "$HINDSIGHT_API_LLM_BASE_URL" ]; then echo "No LLM API key set: starting with HINDSIGHT_API_LLM_PROVIDER=none (storage and recall only, no fact extraction or reflect)"; export HINDSIGHT_API_LLM_PROVIDER=none; fi;; esac; exec hindsight-worker'`
- **Health check:** /health

### Postgres https://devicons.railway.app/i/postgresql.svg

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

### Hindsight API https://cdn.jsdelivr.net/gh/vectorize-io/hindsight@v1.0.0/hindsight-favicon.png

- **Image:** ghcr.io/vectorize-io/hindsight-api:1.0.0
- **Start command:** `/bin/sh -c 'case "$HINDSIGHT_API_LLM_PROVIDER" in ""|openai) if [ -z "$HINDSIGHT_API_LLM_API_KEY" ] && [ -z "$HINDSIGHT_API_LLM_BASE_URL" ]; then echo "No LLM API key set: starting with HINDSIGHT_API_LLM_PROVIDER=none (storage and recall only, no fact extraction or reflect)"; export HINDSIGHT_API_LLM_PROVIDER=none; fi;; esac; exec /app/start-all.sh'`
- **Health check:** /health
- **Public domain:** Yes

### Hindsight Control Plane https://cdn.jsdelivr.net/gh/vectorize-io/hindsight@v1.0.0/hindsight-favicon.png

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

## Documentation

# Deploy and Host Hindsight with Railway

Hindsight, built by Vectorize under the MIT license, gives AI agents a long-term memory they can write to and query across sessions. Memories live in Postgres with pgvector and come back through semantic, keyword, graph and time-aware search with reranking. This template deploys the Hindsight API, a background worker, the web Control Plane and Postgres.

## About Hosting Hindsight

Hindsight 1.0 runs as a FastAPI service with REST and MCP endpoints, an optional pool of workers that process background operations from a Postgres-backed queue, and a Next.js Control Plane for browsing banks, memories, entities and operations. It needs PostgreSQL with the `vector` extension, database migrations before each upgrade, an embedding model, a reranker and, for its full feature set, an LLM. This community template uses the official 1.0.0 images, runs migrations in a pre-deploy step, turns on API key authentication for REST and MCP, protects the Control Plane with an access key, and runs embeddings and reranking on CPU inside the image, so it works without any external key.

## Common Use Cases

- Long-term memory for chatbots, support agents and coding assistants that should remember users and past decisions across sessions
- Shared memory for multi-agent systems through MCP (`/mcp/{bank}/`) or the Python, TypeScript and Go clients
- Per-user or per-customer memory banks with recall that combines semantic, keyword, graph and time-aware search
- Turning raw conversations into extracted facts, entities and consolidated observations an agent can `reflect` on (with an LLM key)
- Inspecting and debugging what an agent knows through the Control Plane's bank, memory, entity and recall views

## Dependencies for Hindsight Hosting

- Postgres with pgvector (included: Railway Postgres 18, which bundles pgvector)
- Embedding and reranking models (included, run on CPU in the API and worker)
- Optional: an LLM API key (OpenAI by default; Anthropic, Gemini, Groq, OpenRouter, DeepSeek, LiteLLM, Ollama and others are supported) for fact extraction, consolidation and reflect

### Deployment Dependencies

- Hindsight repository: https://github.com/vectorize-io/hindsight
- Hindsight documentation: https://hindsight.vectorize.io
- Installation and hardware guide: https://hindsight.vectorize.io/developer/installation
- Configuration reference: https://hindsight.vectorize.io/developer/configuration
- MCP server: https://hindsight.vectorize.io/developer/mcp-server
- pgvector: https://github.com/pgvector/pgvector

### Implementation Details

| Service | Image | Purpose |
|---|---|---|
| Hindsight API | `ghcr.io/vectorize-io/hindsight-api:1.0.0` | REST + MCP API on port 8888 (public), healthcheck `/health`; migrations run in pre-deploy; local embeddings and reranker |
| Hindsight Worker | same image, `hindsight-worker` | Processes async retain, consolidation, mental-model refresh and imports from the Postgres task queue; healthcheck `/health` on 8889 (private) |
| Hindsight Control Plane | `ghcr.io/vectorize-io/hindsight-control-plane:1.0.0` | Web UI on port 9999 (public), access-key login, talks to the API over the private network |
| Postgres | `ghcr.io/railwayapp-templates/postgres-ssl:18` | Banks, memories, vectors, entities and operations, on a volume |

**No LLM key?** The template still starts. Without a key the API and worker switch to Hindsight's no-LLM mode: memories are stored as chunks and recall works, but there is no fact extraction, consolidation or `reflect`. Add `HINDSIGHT_API_LLM_API_KEY` (and `HINDSIGHT_API_LLM_PROVIDER` if not OpenAI) on the Hindsight API service and redeploy the API and worker to enable them; the worker reads the same settings.

**First login**

1. Open the Hindsight Control Plane URL and sign in with `HINDSIGHT_CP_ACCESS_KEY` from that service's Variables tab.
2. Copy `HINDSIGHT_API_TENANT_API_KEY` from the Hindsight API service. Every API and MCP request needs `Authorization: Bearer {your-api-key}`; requests without it get 401.
3. Store a memory: `curl -X POST https://{api-domain}/v1/default/banks/demo/memories -H "Authorization: Bearer {your-api-key}" -H "Content-Type: application/json" -d '{"items":[{"content":"Alice prefers short answers and works in Berlin."}]}'`
4. Recall it: `curl -X POST https://{api-domain}/v1/default/banks/demo/memories/recall -H "Authorization: Bearer {your-api-key}" -H "Content-Type: application/json" -d '{"query":"Where does Alice work?"}'`
5. MCP clients connect to `https://{api-domain}/mcp/{bank}/` with the same header, for example `claude mcp add --transport http hindsight https://{api-domain}/mcp/demo/ --header "Authorization: Bearer {your-api-key}"`. API reference: `https://{api-domain}/docs`.

**Scaling**: the API is stateless; give it more RAM/CPU for heavier recall traffic (reranking runs on CPU). For more background throughput raise `HINDSIGHT_API_WORKER_MAX_SLOTS` on the worker, or duplicate the worker service with a different `HINDSIGHT_API_WORKER_ID`. Do not add replicas to the existing worker: replicas would share one worker id. Connection pools are capped (API 40, worker 30) to fit Postgres' default 100 connections.

**Pinning and upgrades**: all Hindsight services use the `1.0.0` tag. To upgrade, change the tag on the API, worker and Control Plane together, back up Postgres, and redeploy; the API's pre-deploy step migrates the database before the new version takes traffic. Keep `HINDSIGHT_API_EMBEDDINGS_PROVIDER` fixed once memories exist: a different embedding size needs an empty database.

**Resources**: the API and worker each hold the embedding and reranking models in memory (about 1 GB each at idle), so use the Hobby plan or higher. Expect roughly $20 per month at idle and $45 to $50 with regular use, plus your LLM provider's charges.

### Why Deploy Hindsight on Railway?

Railway runs the API, worker, dashboard and database together with private networking, persistent volumes and HTTPS, so your agents get a memory server you control in a few minutes. Your memories stay in your own Postgres, the defaults are locked down, and you can add an LLM key or scale the worker from the dashboard when you need more.


## 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-v1-agent-memory-server