Deploy and Host Agentmemory on Railway

Agentmemory is a persistent memory server for AI coding agents. It keeps what your agents learn about a project — decisions, file layouts, failed approaches, conventions — across sessions and across tools, and serves it back over both a REST API and MCP, so Claude Code, OpenAI Codex CLI, Cursor, Cline, Goose and anything else that speaks MCP share one long-term memory instead of each starting from nothing.

This template deploys it as one service on a volume, running agentmemory 0.9.28 with the matching iii engine, with the API and the real-time viewer both published on the single Railway domain and both behind credentials.

About Hosting Agentmemory

Recall that crosses agents. Agentmemory supports isolating memory per agent with AGENTMEMORY_AGENT_SCOPE=isolated plus an AGENT_ID, which is what you want when several agents or several people share one server. Releases before 0.9.27 applied that filter to smart-search but not to the plain BM25 recall path, so the standard memory_recall tool returned another agent's memories (upstream issue #817). Reproduced on a build pinned to 0.9.16: an instance booted with AGENT_ID=alpha saved "rotate the production database password on Friday"; the same instance rebooted as AGENT_ID=beta recalled that exact sentence. On the 0.9.28 image this template ships, the same query returns no results — the filter now fails closed. Version 0.9.28 also closes the matching leak on POST /agentmemory/context (issue #1057).

The viewer authenticates nobody by itself. Agentmemory's live viewer is useful — sessions, tool calls, timelines, health — and it is also a proxy that adds Authorization: Bearer $AGENTMEMORY_SECRET to every call it forwards. Upstream only requires inbound credentials when the viewer is bound to a non-loopback address; bound to loopback, which is the mode that works behind a gateway, it hands full memory read and write to whoever reaches it. Here the in-container gateway publishes it behind HTTP basic auth (admin, password AGENTMEMORY_SECRET), on the same service and the same port as the API — no second billed service to protect one page.

An empty secret is not a weaker deployment, it is a public one. Agentmemory's auth check is if (!secret) return null: with AGENTMEMORY_SECRET unset, every REST and MCP endpoint answers anonymously, and anyone with the URL can read and write your project's memory. This image refuses to boot with an empty secret rather than starting an open instance. The template generates a 32-character secret for you.

Pinned, and built here rather than on your build minutes. This deploys the prebuilt ghcr.io/bon5co/agentmemory-railway image. Two things are pinned together on purpose: agentmemory registers as a worker against the iii engine, and npm install -g ignores the overrides field agentmemory uses to hold iii-sdk at the engine's version — a global install resolves it up to 0.11.6, the release that moved to a worker model agentmemory has not been refactored for. The image installs into a local prefix with an explicit override and asserts the resolved versions at build time.

State on the volume, and only on the volume. The engine's key-value store, BM25 index and stream backlog are written to absolute paths under the mount — the npm-bundled config uses a relative ./data path, which on Railway lands on the ephemeral overlay. Railway mounts volumes as uid 0 and the app runs as node, so the entrypoint repairs ownership before dropping privileges. Verified across a redeploy: memories saved before the redeploy are recalled after it.

Why Deploy Agentmemory 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 Agentmemory 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.

Common Use Cases

Give Claude Code, Codex CLI, Cursor and Cline one shared project memory that survives session resets and machine changes.
Keep architectural decisions and dead ends where the next agent will actually read them, instead of re-deriving them every session.
Run one memory server for a team or for several agents at once, with per-agent isolation when you want it.

Dependencies for Agentmemory Hosting

A Railway volume mounted at /data.
An MCP-capable agent client (@agentmemory/mcp) or any HTTP client for the REST API.
Optional: an LLM provider key (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY) for compression, summaries and embeddings. Without one the server runs in BM25 + on-device embedding mode, which needs no paid API at all.

Deployment Dependencies

Implementation Details

After the deploy is healthy, copy AGENTMEMORY_SECRET from the service variables and check the API:

export AGENTMEMORY_URL="https://.up.railway.app"
export AGENTMEMORY_SECRET=""

curl -s "$AGENTMEMORY_URL/agentmemory/livez"
curl -s -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
     "$AGENTMEMORY_URL/agentmemory/mcp/tools" | head

Point an agent at it — Codex CLI, in ~/.codex/config.toml:

[mcp_servers.agentmemory]
command = "npx"
args = ["-y", "@agentmemory/mcp"]
enabled = true

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "https://.up.railway.app"
AGENTMEMORY_SECRET = ""
AGENTMEMORY_FORCE_PROXY = "1"

Open the viewer at the service URL in a browser: username admin, password AGENTMEMORY_SECRET. Change the username with AGENTMEMORY_VIEWER_USER if you like.

To isolate memory per agent, set AGENTMEMORY_AGENT_SCOPE=isolated and give each client its own AGENT_ID.