Deploy and Host Agentmemory on Railway

Agentmemory (github : https://github.com/rohitg00/agentmemory) is a persistent memory server for AI coding agents. It stores useful project context across sessions on a Railway volume and exposes that memory through REST and MCP so tools such as OpenAI Codex CLI, Claude Code, Cursor, Cline, Goose, and other compatible agents can share the same long-term project memory.

About Hosting Agentmemory

This Railway template pins Agentmemory 0.9.30 and iii engine/SDK 0.22.1, with noninteractive startup and a Caddy-protected viewer. It runs Agentmemory as an always-on backend for your AI coding tools. Railway provides the public HTTPS URL, runtime variables, and persistent storage volume. Agentmemory stores memory under /data, keeps state across redeploys, and exposes a protected REST API under /agentmemory/*.

The public service should expose only the REST API. Internal streams, the iii-engine port, and the optional viewer should remain private unless you intentionally protect them with a reverse proxy such as Caddy with Basic Auth.

Quick Start

The API is protected with AGENTMEMORY_SECRET. Calling the health endpoint without authentication may return 401 unauthorized.

Test your deployment with a Bearer token:

export AGENTMEMORY_URL="https://your-template-url"
export AGENTMEMORY_SECRET="your-generated-secret"

curl -i \
  -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
  "$AGENTMEMORY_URL/agentmemory/health"

A healthy authenticated deployment should return HTTP 200.

Use the same URL and secret in each client:

AGENTMEMORY_URL="https://your-template-url"
AGENTMEMORY_SECRET="your-generated-secret"

Codex CLI MCP Setup

Install the MCP shim globally for faster startup:

npm install -g @agentmemory/mcp@0.9.30
which agentmemory-mcp

Then add this to ~/.codex/config.toml:

[mcp_servers.agentmemory]
command = "/opt/homebrew/bin/agentmemory-mcp"
args = []
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 120

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "https://your-template-url"
AGENTMEMORY_SECRET = "your-generated-secret"
AGENTMEMORY_FORCE_PROXY = "1"

If you prefer not to install globally, you can use npx, but first startup may be slower:

[mcp_servers.agentmemory]
command = "npx"
args = ["-y", "@agentmemory/mcp@0.9.30"]
enabled = true
startup_timeout_sec = 90
tool_timeout_sec = 120

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "https://your-template-url"
AGENTMEMORY_SECRET = "your-generated-secret"
AGENTMEMORY_FORCE_PROXY = "1"

After starting Codex, run /mcp. You should see the agentmemory server and tools such as memory_save, memory_recall, memory_smart_search, memory_sessions, and memory_diagnose.

Validate Real Usage

Ask Codex:

Use agentmemory to remember this fact: this project uses a Railway-hosted Agentmemory server with REST API on port 8080 and persistent storage mounted at /data.

Then ask in a new prompt:

Search agentmemory for what this project uses port 8080 for.

If Codex recalls that port 8080 is used for the Railway-hosted Agentmemory REST API, the full path is working:

Codex -> agentmemory-mcp -> Railway Agentmemory API -> /data volume -> recall/viewer

Recommended Railway Variables

PORT="8080" # Railway routes public traffic to this port.
NODE_ENV="production" # Runs Node and dependencies in production mode.
III_DATA_DIR="/data" # Stores iii-engine persistent data on the Railway volume.
AGENTMEMORY_DATA_DIR="/data" # Stores Agentmemory persistent memory data on the Railway volume.
AGENTMEMORY_SECRET="${{secret(32)}}" # Shared secret for authenticated Agentmemory requests.
VIEWER_ALLOWED_HOSTS="${{agentmemory viewer caddy.RAILWAY_PUBLIC_DOMAIN}}" # Trusted viewer hostname.
VIEWER_ALLOWED_ORIGINS="https://${{agentmemory viewer caddy.RAILWAY_PUBLIC_DOMAIN}}" # Allowed HTTPS viewer origin.
PUBLIC_AGENTMEMORY_URL="https://${{RAILWAY_PUBLIC_DOMAIN}}" # Public HTTPS URL used by clients.

Recommended volume mount path:

/data

Recommended public networking target port:

Public and Private Ports

The deployment should expose only the REST API publicly:

REST API: public on Railway PORT, usually 8080
Streams: internal only
Viewer: internal or protected
iii-engine: internal only
Persistent storage: /data Railway volume

The optional viewer is useful for inspecting sessions, memory, tool calls, timelines, and health state, but it may expose sensitive project and prompt data. Do not expose it directly without authentication.

Example protected viewer upstream:

UPSTREAM_URL="http://${{agentmemory.RAILWAY_PRIVATE_DOMAIN}}:8083"
AUTH_USER="user"
AUTH_PASS="your-password"

Sign in to the viewer with AUTH_USER and AUTH_PASS from the Caddy service. Its private relay carries HTTP requests and live WebSocket updates. For custom viewer domains, update both VIEWER_ALLOWED_HOSTS and VIEWER_ALLOWED_ORIGINS, then redeploy Agentmemory. Railway supplies public HTTPS.

Dependencies for Agentmemory

Railway with a persistent volume mounted at /data.
The bundled Agentmemory 0.9.30 and iii 0.22.1 runtime.
Caddy for authenticated viewer access.

Optional LLM Providers

This template intentionally deploys without any LLM provider key. A fresh deployment may log:

No LLM provider key found
Provider: noop
Embedding provider: none (BM25-only mode)

This is expected and not fatal. Agentmemory still runs, stores memory, serves REST/MCP requests, and can use non-LLM retrieval. This default avoids requiring paid API keys, prevents unexpected token usage, and lets users deploy immediately.

Agentmemory auto-detects LLM providers from environment variables. Supported provider keys include ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, and MINIMAX_API_KEY. Gemini can also enable embeddings. The no-op provider is the default when no provider key is present.

To enable LLM-backed compression and summarization later, add one provider key and redeploy:

ANTHROPIC_API_KEY="..."
# or
GEMINI_API_KEY="..."
# or
OPENROUTER_API_KEY="..."
# or
MINIMAX_API_KEY="..."

AGENTMEMORY_AUTO_COMPRESS="true"

For OpenAI embeddings:

OPENAI_API_KEY="..."
EMBEDDING_PROVIDER="openai"
OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
OPENAI_EMBEDDING_DIMENSIONS="1536"

For local embeddings, you may use:

EMBEDDING_PROVIDER="local"

Local embeddings may require optional transformer dependencies in the image, so this template does not enable them by default.

Do not enable this by default in a public template:

AGENTMEMORY_ALLOW_AGENT_SDK="true"

That fallback can launch Claude Agent SDK sessions, consume a user’s Claude allocation, and may recurse in some Claude Code hook setups.

Common Use Cases

Share long-term coding memory across Codex CLI, Claude Code, Cursor, Cline, Goose, and other MCP-compatible agents.
Persist project architecture, debugging history, implementation decisions, preferences, and lessons learned.
Run Agentmemory as a remote personal or team memory backend instead of depending on local-only state.
Connect custom tools or non-MCP agents directly through the REST API.
Inspect memory and sessions through the optional viewer behind authentication.

Troubleshooting

`GET /` returns `404`

This is expected. Agentmemory serves its REST API under /agentmemory/*, not at the root path.

`/agentmemory/health` returns `401 unauthorized`

The API is reachable but protected. Send the Bearer token:

curl -i \
  -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
  "$AGENTMEMORY_URL/agentmemory/health"

Codex MCP startup times out

Install the MCP shim globally and point Codex directly at the binary instead of using npx:

npm install -g @agentmemory/mcp@0.9.30
which agentmemory-mcp

Then use the absolute path in ~/.codex/config.toml and set startup_timeout_sec = 60 or higher.

`No LLM provider key found`

This is not fatal. Agentmemory runs with the no-op LLM provider. Compression and summarization that require an LLM are disabled, while non-LLM retrieval can still work.

If you want LLM-backed compression and summarization, add one provider key and enable auto-compression:

OPENROUTER_API_KEY="..."
AGENTMEMORY_AUTO_COMPRESS="true"

Other supported provider keys include:

ANTHROPIC_API_KEY="..."
GEMINI_API_KEY="..."
MINIMAX_API_KEY="..."

First-run onboarding appears in logs

This template stores preferences at /data/.agentmemory/preferences.json and initializes the first-run state automatically. It runs under the unprivileged node user and keeps the API secret supplied by Railway. Railway health checks use /agentmemory/livez; the full /agentmemory/health endpoint remains authenticated.

Secret rotation

If your AGENTMEMORY_SECRET is exposed, rotate it in Railway and update every client configuration:

AGENTMEMORY_SECRET="${{secret(32)}}"

Redeploy the service after changing the secret.

Deployment Dependencies

Agentmemory GitHub: https://github.com/rohitg00/agentmemory
Agentmemory npm package: https://www.npmjs.com/package/@agentmemory/agentmemory
Agentmemory MCP shim: https://www.npmjs.com/package/@agentmemory/mcp
OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp

Why Deploy on Railway?

Railway hosts the service, provides HTTPS networking, injects runtime variables, and mounts persistent storage with minimal setup. By deploying Agentmemory on Railway, you get a remote shared memory backend for AI agents without maintaining a server manually.