Hindsight v1 Agent Memory Server
Hindsight 1.0.0, by Vectorize under the MIT license, gives AI agents long-term memory they can write to and query across sessions. This template deploys the API, a background worker, the web Control Plane and Postgres with pgvector, with API key authentication turned on.
What you get
- Hindsight API with REST and MCP endpoints, bearer-token authentication and migrations run in a pre-deploy step
- A background worker that processes retain, consolidation and import jobs from a Postgres-backed queue
- Control Plane web UI for browsing banks, memories, entities and operations, protected by an access key
- Postgres 18 with pgvector on a volume
- Embeddings and reranking running on CPU inside the image, so no external key is needed to start
Good for
- Long-term memory for chatbots, support agents and coding assistants
- Shared memory for multi-agent systems through MCP or the client libraries
- Per-user or per-customer memory banks with combined semantic, keyword, graph and time-aware recall
- Inspecting what an agent knows through the Control Plane
Services in this template
- Hindsight Worker · image
ghcr.io/vectorize-io/hindsight-api:1.0.0 - Postgres · image
ghcr.io/railwayapp-templates/postgres-ssl:18 - Hindsight API · image
ghcr.io/vectorize-io/hindsight-api:1.0.0 - Hindsight Control Plane · image
ghcr.io/vectorize-io/hindsight-control-plane:1.0.0
Questions people ask
How do I log in and call the API?
Sign in to the Control Plane with HINDSIGHT_CP_ACCESS_KEY from its Variables tab. Copy HINDSIGHT_API_TENANT_API_KEY from the API service; every API and MCP request needs Authorization: Bearer with that key, and requests without it get 401. The API reference is at /docs on the API domain.
Does it work without an LLM key?
It starts, but in no-LLM mode: memories are stored as chunks and recall works, with no fact extraction, consolidation or reflect. Set HINDSIGHT_API_LLM_API_KEY (and HINDSIGHT_API_LLM_PROVIDER if not OpenAI) on the API service and redeploy the API and worker to enable them.
How do I scale the worker?
Raise HINDSIGHT_API_WORKER_MAX_SLOTS, or duplicate the worker service with a different HINDSIGHT_API_WORKER_ID. Do not add replicas to the existing worker, because replicas would share one worker id.
How do I upgrade?
Change the 1.0.0 tag on the API, worker and Control Plane together, back up Postgres and redeploy; the pre-deploy step migrates the database. Keep HINDSIGHT_API_EMBEDDINGS_PROVIDER fixed once memories exist, since a different embedding size needs an empty database.
Full template README
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
reflecton (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
- Open the Hindsight Control Plane URL and sign in with
HINDSIGHT_CP_ACCESS_KEYfrom that service's Variables tab. - Copy
HINDSIGHT_API_TENANT_API_KEYfrom the Hindsight API service. Every API and MCP request needsAuthorization: Bearer {your-api-key}; requests without it get 401. - 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."}]}' - 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?"}' - MCP clients connect to
https://{api-domain}/mcp/{bank}/with the same header, for exampleclaude 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.
Guides for this template
View Hindsight v1 Agent Memory Server on railway.com
Similar templates
| Template | Category | DeploymentsDeploys |
|---|---|---|
| 9Router Self-hosted AI router for Claude, Gemini, Cursor & OpenAI tools. | AI/ML | 9,734 |
| flowise-railway Flowise - low-code LLM apps builder | AI/ML | 8,512 |
| LibreChat Open-source ChatGPT clone: multi-model, agents, search, multi-user auth | AI/ML | 6,762 |
| Hermes Agent by Nous Research Template for Hermes Agent by Nous Research | AI/ML | 6,413 |
| OpenClaw [Homebrew support] The AI that actually does things | AI/ML | 5,167 |
| Hermes Agent Self Host Hermes Agent. Autonomous AI agent w/ self-improving, tools & more | AI/ML | 4,092 |