Deploy and Host Hindsight Memory Server on Railway

Hindsight is an open-source (MIT) memory server for AI agents. Your agent sends it things worth remembering and asks it questions later. Hindsight uses an LLM to pull facts and entities out of what you store, and searches them with embeddings in Postgres.

I wanted Hindsight with auth on from the first deploy and the memories on a volume, and I didn't want to pull a 9 GB image, so I put this template together. The API needs a key on every request, the web UI has its own password, and Postgres with pgvector keeps its data on a Railway volume.

You need one thing to deploy it: an OpenAI API key. It covers both the LLM and the embeddings. OpenRouter also works, and the setup is further down.

On a fresh deploy the whole stack idled at about 570 MB of RAM in my tests (API 371 MB, Postgres 135 MB, UI 65 MB), and the deploy finished in about 80 seconds. I'd run it on the Hobby plan.

About Hosting Hindsight Memory Server

The template runs three services:

hindsight-api is the REST API and MCP server (slim image, pinned to 0.10.1)
hindsight-ui is the web UI, which Hindsight calls the control plane
Postgres runs pgvector/pgvector:pg17 with a volume

The API runs its migrations on boot and creates the pgvector extension itself. Railway's healthcheck hits /health, which only returns 200 once the database is connected, so traffic doesn't reach a deploy that isn't ready. The UI talks to the API over the private network with the same key, so you never paste the API key into a browser.

When the deploy is done, copy HINDSIGHT_API_TENANT_API_KEY from the Variables tab of hindsight-api. That's your API key. The UI password is HINDSIGHT_CP_ACCESS_KEY on hindsight-ui.

Then check that the API answers:

curl https://YOUR-API-DOMAIN/v1/default/banks \
  -H "Authorization: Bearer YOUR_API_KEY"

You should get {"banks":[],"total":0,...} back. Without the header it returns 401.

Common Use Cases

If you use Claude Code or Cursor, you can add Hindsight as an MCP server and your agent gets retain, recall and reflect tools. Each memory bank has its own endpoint at /mcp//:

claude mcp add --transport http hindsight https://YOUR-API-DOMAIN/mcp/my-bank/ \
  --header "Authorization: Bearer YOUR_API_KEY"

You can also call it from your own agent with the official clients:

from hindsight_client import Hindsight

client = Hindsight(base_url="https://YOUR-API-DOMAIN", api_key="YOUR_API_KEY")
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")
print(client.recall(bank_id="my-bank", query="Where does Alice work?"))

const { HindsightClient } = require("@vectorize-io/hindsight-client");

const client = new HindsightClient({ baseUrl: "https://YOUR-API-DOMAIN", apiKey: "YOUR_API_KEY" });
await client.retain("my-bank", "Alice loves hiking in Yosemite");
console.log(await client.recall("my-bank", "What does Alice like?"));

I ran that retain and recall against this template before publishing it. The fact came back from recall about six seconds after the retain call returned.

Banks keep memories apart, so one server can hold a bank per user, per project or per agent.

Dependencies for Hindsight Memory Server Hosting

An OpenAI API key, or an OpenRouter key. Hindsight calls the LLM to extract facts from what you store and the embeddings model to search them. Reranking is set to rrf (reciprocal rank fusion), which doesn't need a model or a key.

Deployment Dependencies

Hindsight source: https://github.com/vectorize-io/hindsight
Hindsight docs: https://hindsight.vectorize.io
Images: ghcr.io/vectorize-io/hindsight-api:0.10.1-slim, ghcr.io/vectorize-io/hindsight-control-plane:0.10.1 and pgvector/pgvector:pg17

Implementation Details

To use OpenRouter instead of OpenAI, set these on hindsight-api. I tested this exact setup on the template. Storing one memory used about 3,100 tokens, which came to $0.001 with gpt-4o-mini.

HINDSIGHT_API_LLM_PROVIDER=openrouter
HINDSIGHT_API_LLM_API_KEY=
HINDSIGHT_API_LLM_MODEL=openai/gpt-4o-mini
HINDSIGHT_API_EMBEDDINGS_PROVIDER=openrouter
HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL=openai/text-embedding-3-small

Pick your embedding model before you store anything. The vector size depends on the model (1536 for text-embedding-3-small), and vectors from one model can't be searched with another.

For another LLM provider, change HINDSIGHT_API_LLM_PROVIDER (anthropic, gemini, groq, deepseek and others) and put that provider's key in HINDSIGHT_API_LLM_API_KEY. Embeddings stay on OpenAI unless you change them, so either add HINDSIGHT_API_EMBEDDINGS_API_KEY with an OpenAI key or choose another embeddings provider from the configuration docs.

I went with the slim image because the full one is about 9 GB. It bundles local embedding and reranking models, and Hindsight's docs recommend 2 GB of RAM for it. With hosted embeddings and rrf you don't need those models.

Both services listen on 0.0.0.0. My first version used ::, and uvicorn then listened on IPv6 only, so Railway's public domain returned 502. Railway's private network resolves IPv4 as well, so the UI still reaches the API.

To upgrade, set the same new release tag on hindsight-api and hindsight-ui. Migrations run on boot. Back up the Postgres volume first.

/health and /docs are public. /docs is only the API reference page, and every data and MCP route needs the key. Anyone who has the key can read and write your memories, so keep it with your other secrets.

Why Deploy Hindsight Memory Server on Railway?

Railway runs the three services, the private network between them and the Postgres volume, so there's no server for you to patch. The API and the UI each get an HTTPS domain, and you pay for what the stack uses. For this one that's a bit over half a GB of RAM at idle.