---
title: "Deploy Agentmemory - Self-hosted Memory for AI Agents"
description: "Persistent memory server for MCP agents. agentmemory agent memory"
category: "AI/ML"
url: https://railway.com/deploy/agentmemory-self-hosted-memory-for-ai-ag
---

# Deploy Agentmemory - Self-hosted Memory for AI Agents

Persistent memory server for MCP agents. agentmemory agent memory

**[Deploy Agentmemory - Self-hosted Memory for AI Agents on Railway](https://railway.com/template/agentmemory-self-hosted-memory-for-ai-ag)**

- **Creator:** Xav's Projects
- **Category:** AI/ML
- **Total deploys:** 23

## Template content

### agentmemory viewer caddy https://media.rubrion.ai/railway/icons/caddy.svg

- **Source:** https://github.com/XavTo/caddy-zero-trust
- **Public domain:** Yes

### agentmemory https://bc.xavto.fr/xavto/agentmemory.svg

- **Source:** https://github.com/XavTo/agentmemory
- **Public domain:** Yes

## Documentation

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

```bash
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:

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

## Codex CLI MCP Setup

Install the MCP shim globally for faster startup:

```bash
npm install -g @agentmemory/mcp
which agentmemory-mcp
```

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

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

```toml
[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:

```txt
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:

```txt
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:

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

## Recommended Railway Variables

```env
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:

```txt
/data
```

Recommended public networking target port:

```txt
8080
```

## Public and Private Ports

The deployment should expose only the REST API publicly:

```txt
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:

```env
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:

```txt
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:

```env
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:

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

For local embeddings, you may use:

```env
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:

```env
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:

```bash
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`:

```bash
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:

```env
OPENROUTER_API_KEY="..."
AGENTMEMORY_AUTO_COMPRESS="true"
```

Other supported provider keys include:

```env
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:

```env
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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/agentmemory-self-hosted-memory-for-ai-ag