Deploy and Host Agentmemory - Self-hosted Memory for AI Agents on Railway

Agentmemory is a persistent memory server for AI coding agents. It captures useful context across sessions, stores it on a Railway volume, and exposes 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.

How to Use This Template

Deploy the template on Railway and wait for the agentmemory service to become healthy. Railway exposes the Agentmemory REST API through the generated public domain and persists memory data on the mounted /data volume.

This template protects the public API with AGENTMEMORY_SECRET. Because of that, calling the health endpoint without authentication may return 401 unauthorized. Test the 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 generated public URL and secret in your MCP client configuration:

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

For MCP-based clients, configure the standalone MCP shim. For OpenAI Codex CLI, install the 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.

To validate real usage in Codex, ask:

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

In real-world use, connect all your coding agents to the same Railway-hosted Agentmemory URL. This lets them reuse project knowledge, past debugging discoveries, architectural decisions, repeated preferences, and lessons learned instead of starting from a blank session every time.

What is Agentmemory - Self-hosted Memory for AI Agents?

Agentmemory gives AI coding agents a shared, persistent memory layer. It works with agents that support hooks, MCP, or REST APIs, allowing them to store observations, search previous sessions, recall project context, and reuse lessons learned across tools, repositories, and coding sessions without relying only on local prompt files.

About Hosting Agentmemory - Self-hosted Memory for AI Agents

Hosting Agentmemory on Railway means running the memory server as an always-on backend for your AI agents. Railway provides the public HTTPS endpoint, injects runtime variables, and mounts a persistent volume at /data so memory survives restarts and redeployments.

This template configures Agentmemory to listen on Railway’s runtime port, stores iii-engine and Agentmemory data on the volume, and protects the REST API with a shared secret. 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.

The default deployment can run without any LLM provider key. In that mode, Agentmemory uses no-op LLM summarization and BM25/graph-based retrieval. This is useful for templates because it avoids requiring paid API keys. If you want LLM-backed compression and summarization, add a supported provider key later.

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 across sessions and redeploys.
Run Agentmemory as a remote personal or team memory backend instead of depending on local-only state.
Connect non-MCP tools directly through the REST API for custom agent workflows.
Inspect memory and sessions through the optional viewer behind a password-protected reverse proxy.

Dependencies for Agentmemory - Self-hosted Memory for AI Agents Hosting

A Railway service running the Agentmemory container.
A Railway volume mounted at /data for persistent memory, state, and stream storage.
A public Railway domain routed to the Agentmemory REST API port.
A secure AGENTMEMORY_SECRET shared between the Railway service and your clients.
One or more MCP, hook-based, or REST-compatible AI agents configured to use the Railway URL.
Optional LLM provider keys if you want LLM-backed compression and summarization instead of the default no-op provider.
Optional Caddy or another reverse proxy if you want to expose the viewer safely.

Deployment Dependencies

Agentmemory GitHub repository: 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 documentation: https://developers.openai.com/codex/mcp

Implementation Details

Recommended Railway variables:

PORT="8080" # Railway routes public traffic to this port; Agentmemory must listen on the same port.
NODE_ENV="production" # Runs Node.js and dependencies in production mode.
III_DATA_DIR="/data" # Stores iii-engine persistent data on the Railway volume.
AGENTMEMORY_URL="https://${{RAILWAY_PUBLIC_DOMAIN}}" # Public HTTPS URL used by clients to reach the Agentmemory REST API.
AGENTMEMORY_SECRET="${{secret(32)}}" # Railway-generated shared secret used to protect authenticated Agentmemory requests.
AGENTMEMORY_DATA_DIR="/data" # Stores Agentmemory persistent memory data on the Railway volume.
AGENTMEMORY_REQUIRE_HTTPS="1" # Requires HTTPS for public access, matching Railway's public domain behavior.

Recommended volume mount path:

/data

Recommended public networking target port:

The deployment should expose only the REST API publicly:

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

If the optional viewer is enabled, protect it with authentication. The 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 access control.

Example Caddy upstream for a separate protected viewer proxy:

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

Troubleshooting

`GET /` returns `404`

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

`/agentmemory/health` returns `401 unauthorized`

This means 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 will run with no-op LLM summarization and BM25/graph retrieval. Add a provider key only if you want LLM-backed compression and summarization:

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

Do not enable AGENTMEMORY_ALLOW_AGENT_SDK=true by default in a public template. It can consume a user’s Claude Pro allocation and may cause recursion in some Claude Code hook setups.

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.

Why Deploy Agentmemory - Self-hosted Memory for AI Agents 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 - Self-hosted Memory for AI Agents 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.