---
title: "Deploy Statewave Agent Memory"
description: "Open-source memory runtime for AI agents + admin console, with pgvector"
category: "AI/ML"
url: https://railway.com/deploy/statewave-agent-memory
---

# Deploy Statewave Agent Memory

Open-source memory runtime for AI agents + admin console, with pgvector

**[Deploy Statewave Agent Memory on Railway](https://railway.com/template/statewave-agent-memory)**

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

- **Creator:** My Projects
- **Category:** AI/ML

## Template content

### statewave-api https://raw.githubusercontent.com/smaramwbc/statewave-admin/main/public/favicon.svg

- **Image:** statewavedev/statewave:latest
- **Health check:** /healthz
- **Public domain:** Yes

### statewave-admin https://raw.githubusercontent.com/smaramwbc/statewave-admin/main/public/favicon.svg

- **Image:** statewavedev/statewave-admin:latest
- **Public domain:** Yes

### pgvector https://raw.githubusercontent.com/devicons/devicon/master/icons/postgresql/postgresql-original.svg

- **Image:** pgvector/pgvector:pg16

## Documentation

# Deploy and Host Statewave Agent Memory on Railway

[Statewave](https://github.com/smaramwbc/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:**
1. Open the **statewave-admin** domain and sign in with the `ADMIN_PASSWORD` value from the statewave-admin service's *Variables* tab.
2. Call the API from your agents at the **statewave-api** domain with header `X-API-Key: YOUR_STATEWAVE_API_KEY`.
3. 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/statewave-agent-memory