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.

What This Template Deploys

This Railway template 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
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"
AGENTMEMORY_DEBUG = "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"]
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"
AGENTMEMORY_DEBUG = "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.
AGENTMEMORY_REQUIRE_HTTPS="1" # Requires HTTPS for public access.
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}}:8082"
AUTH_USER="user"
AUTH_PASS="your-password"

LLM Provider Keys Are Optional

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 a simple all-in-one setup, GEMINI_API_KEY is a good option because Agentmemory can use Gemini for both LLM features and embeddings.

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
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

Recent Agentmemory versions use ~/.agentmemory/preferences.json to track first-run state. In a container template, the startup script should create /app/.agentmemory/preferences.json with a non-null firstRunAt value so Railway does not block on an interactive CLI prompt.

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.

Useful Links

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.