Deploy and Host Statewave Agent Memory on Railway

Statewave is an open-source memory runtime for AI agents: it turns raw conversations ("episodes") into durable, provenance-tagged memories and builds reproducible, token-budgeted context for every agent call. It ships with an operator admin console for browsing subjects, memories and persona health.

About Hosting Statewave

This template deploys the complete Statewave stack, fully wired over Railway's private network:

Service	Image	Purpose
statewave-api	`statewavedev/statewave`	FastAPI memory server (port 8100), runs DB migrations automatically on boot
statewave-admin	`statewavedev/statewave-admin`	Password-protected operator console (port 8080)
pgvector	`pgvector/pgvector:pg16`	PostgreSQL 16 + pgvector on a persistent volume

All secrets are generated per deployment: the API key (STATEWAVE_API_KEY), the admin password (ADMIN_PASSWORD), session secret, admin master key and database password.

After deploy:

Open the statewave-admin domain and sign in with the ADMIN_PASSWORD value from the statewave-admin service's Variables tab.
Call the API from your agents at the statewave-api domain with header X-API-Key: YOUR_STATEWAVE_API_KEY.
Five demo agent personas are seeded automatically, so you can explore right away.

Common Use Cases

Long-term, per-user memory for chatbots, copilots and support agents
Reproducible context building with token budgets and provenance for every memory
Self-hosted alternative to hosted agent-memory APIs (data stays in your Postgres)
Semantic memory search with pgvector once an LLM/embedding provider is configured

Dependencies for Statewave Hosting

PostgreSQL with the pgvector extension (included)
Optional: any LiteLLM-supported provider (OpenAI, Anthropic, Azure, Bedrock, Ollama…) for LLM extraction and real embeddings

Deployment Dependencies

API source: https://github.com/smaramwbc/statewave
Admin source: https://github.com/smaramwbc/statewave-admin

Implementation Details

The template starts in keyless demo mode (heuristic compiler + stub embeddings) so it runs with zero external calls. To enable LLM-driven memory extraction and semantic search, add these variables to statewave-api:

STATEWAVE_COMPILER_TYPE=llm
STATEWAVE_EMBEDDING_PROVIDER=litellm
STATEWAVE_LITELLM_API_KEY=sk-...
STATEWAVE_LITELLM_MODEL=gpt-4o-mini
STATEWAVE_LITELLM_EMBEDDING_MODEL=text-embedding-3-small

Why Deploy Statewave on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Statewave on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.