How to Start the ai-memory HTTP+MCP Server: 3 Deployment Methods

Run ai-memory serve after initializing with ai-memory init, or use the systemd service or Docker container for production deployments.

The ai-memory project from akitaonrails/ai-memory provides a single-process HTTP server that exposes both an MCP (Model Context Protocol) JSON-RPC-like API for agents and a Web UI for browsing markdown documentation. This guide covers the three standard ways to start the server: systemd service, Docker container, and manual foreground execution.

---

Installation Options

Before starting the server, install the binary using one of these methods:

# From source (requires Rust toolchain)

cargo install --locked ai-memory

# On Arch Linux via AUR (pre-built binary)

yay -S ai-memory-bin

# Or build from source via AUR

yay -S ai-memory

The repository also ships a thin wrapper script at bin/ai-memory that forwards arguments to the binary when running inside Docker.

---

Step 1: Initialize Configuration and Data Directory

All deployment methods share the same configuration files. Run the init sub-command once to create them:

mkdir -p ~/.local/share/ai-memory ~/.config/ai-memory

ai-memory \
  --data-dir ~/.local/share/ai-memory \
  --config   ~/.config/ai-memory/config.toml \
  init

The init command writes a minimal config.toml and prepares the SQLite store location. This step is required before first server startup.

---

Step 2: Start the ai-memory HTTP+MCP Server

Choose one of the three deployment methods based on your environment.

Method 1: Systemd Service (Recommended for Production)

The AUR packages and binary releases include a systemd unit file.

# User-level service (runs on login, no root required)

systemctl --user enable --now ai-memory.service

# Or system-wide (requires root)

sudo systemctl enable --now ai-memory.service

The service launches with your configured --data-dir and --config values, binding to 127.0.0.1:49374 by default. Check status with:

systemctl --user status ai-memory.service

Method 2: Docker Container (Isolated, Quick Setup)

docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    akitaonrails/ai-memory:latest

The container automatically starts the HTTP+MCP server. For authentication in containerized deployments, add:

-e AI_MEMORY_AUTH_TOKEN=your-secret-token

Method 3: Manual Foreground Run (Development and Debugging)

ai-memory \
  --data-dir ~/.local/share/ai-memory \
  --config   ~/.config/ai-memory/config.toml \
  serve

Important flags for the serve sub-command:

Flag	Purpose
--bind 0.0.0.0:49374	Listen on all interfaces (required for remote access)
--enable-web	Enable the /web UI and read-only /api/v1 JSON API
--auth-token <TOKEN>	Require bearer token for non-loopback requests

Omitting the sub-command defaults to serve, as implemented in crates/ai-memory-cli/src/main.rs.

---

Verify Server Operation

Test that the ai-memory HTTP+MCP server is responding:

# Health check endpoint

curl -s http://127.0.0.1:49374/status | jq .

Expected output includes version, uptime, and LLM/embedding health status. With --enable-web, open the UI at:

http://127.0.0.1:49374/web

If authentication is enabled, supply the token as the HTTP Basic password (username is ignored).

---

Connect an MCP Client Agent

After the server runs, configure your AI coding agent to use it:

# Install MCP configuration for Claude Code

ai-memory install-mcp   --client claude-code --apply

# Install lifecycle hooks for automatic context capture

ai-memory install-hooks --agent  claude-code --apply

These commands write client-specific configuration (e.g., ~/.claude.json) pointing to http://127.0.0.1:49374 with the configured bearer token.

---

Complete Setup Example

# 1. Initialize (run once)

mkdir -p ~/.local/share/ai-memory ~/.config/ai-memory
ai-memory \
  --data-dir ~/.local/share/ai-memory \
  --config   ~/.config/ai-memory/config.toml \
  init

# 2. Start with web UI enabled

ai-memory \
  --data-dir ~/.local/share/ai-memory \
  --config   ~/.config/ai-memory/config.toml \
  serve --enable-web

# 3. Verify health

curl -s http://127.0.0.1:49374/status | jq .

# 4. Configure Claude Code integration

ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

---

Key Source Files in the Repository

Understanding the implementation helps with troubleshooting:

• crates/ai-memory-cli/src/main.rs — CLI entry point with Clap argument parsing; defines init, serve, status sub-commands
• crates/ai-memory-mcp/src/lib.rs — Core MCP HTTP server implementing /mcp, /hook, and /handoff routes
• crates/ai-memory-web/src/main.rs — Web UI server for /web and /api/v1 endpoints
• bin/ai-memory — Docker wrapper script for containerized deployments
• docs/install.md — Extended installation and systemd configuration guide
• docs/ARCHITECTURE.md — High-level server architecture documentation

---

Summary

• Initialize once with ai-memory init to create config.toml and data directories
• Choose deployment method: systemd for persistence, Docker for isolation, or manual serve for debugging
• Default bind address is 127.0.0.1:49374 — use --bind 0.0.0.0:49374 for remote access
• Enable web features with --enable-web to access /web UI and /api/v1 JSON API
• Configure agents using install-mcp and install-hooks sub-commands after server startup

---

Frequently Asked Questions

How do I change the default port for the ai-memory server?

Pass the --bind flag with your desired address and port. For example: --bind 0.0.0.0:8080 listens on port 8080 across all interfaces. The default 127.0.0.1:49374 restricts access to localhost only.

What is the difference between the MCP API and the Web UI?

The MCP API at /mcp and /hook provides a JSON-RPC-like interface for AI agents to read and write context. The Web UI at /web is a read-only markdown browser for humans, plus a read-only JSON API at /api/v1. Enable the Web UI with --enable-web or the AI_MEMORY_ENABLE_WEB environment variable.

Can I run ai-memory without installing Rust?

Yes. Use the Docker image (akitaonrails/ai-memory:latest) or install a pre-built binary via AUR (yay -S ai-memory-bin). Both options avoid compiling from source.

How do I secure the server when exposing it beyond localhost?

Set a static bearer token using --auth-token <TOKEN> or the AI_MEMORY_AUTH_TOKEN environment variable. When making requests, provide this token as the HTTP Basic password (any username works). The server rejects unauthenticated requests from non-loopback addresses when authentication is configured.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}