# How to Start the ai-memory HTTP+MCP Server: 3 Deployment Methods > Easily start the ai-memory HTTP+MCP server with `ai-memory serve` or explore systemd and Docker deployment options. Get your AI memory project running quickly and efficiently. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: how-to-guide - Published: 2026-08-28 --- **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: ```bash # 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: ```bash 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`](https://github.com/akitaonrails/ai-memory/blob/main/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. ```bash # 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: ```bash systemctl --user status ai-memory.service ``` ### Method 2: Docker Container (Isolated, Quick Setup) ```bash 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: ```bash -e AI_MEMORY_AUTH_TOKEN=your-secret-token ``` ### Method 3: Manual Foreground Run (Development and Debugging) ```bash 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 ` | Require bearer token for non-loopback requests | Omitting the sub-command defaults to `serve`, as implemented in [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs). --- ## Verify Server Operation Test that the ai-memory HTTP+MCP server is responding: ```bash # 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: ```bash # 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 ```bash # 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs)** — Core MCP HTTP server implementing `/mcp`, `/hook`, and `/handoff` routes - **[`crates/ai-memory-web/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md)** — Extended installation and systemd configuration guide - **[`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md)** — High-level server architecture documentation --- ## Summary - **Initialize once** with `ai-memory init` to create [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/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 ` 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.