How to Set Up ai-memory as a Self-Contained Rust Binary: Complete Native Installation

Compile ai-memory from source using the pinned Rust toolchain in rust-toolchain.toml, then run the init, serve, and install-mcp subcommands to create a native SQLite-backed memory server that integrates directly with coding agents.

ai-memory is a Rust-based persistence layer for AI coding agents that stores conversation context in a local database and markdown wiki. Setting it up as a self-contained Rust binary produces a single native executable capable of hosting the HTTP server, managing file storage, and registering Model Context Protocol (MCP) clients without Docker or external runtime dependencies.

Build the Self-Contained Binary

The ai-memory workspace defines the CLI binary in crates/ai-memory-cli/Cargo.toml and pins the required compiler version in rust-toolchain.toml to ensure reproducible builds.

Install the Rust toolchain and compile the release binary:

# Install the pinned Rust version (1.95+)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup show  # Verifies the toolchain specified in rust-toolchain.toml

# Clone and build

git clone https://github.com/akitaonrails/ai-memory.git
cd ai-memory
cargo build --release -p ai-memory-cli

The resulting executable is available at ./target/release/ai-memory. This binary encapsulates all server logic, SQLite management, and agent integration hooks in a single file.

Initialize the Data Directory

Before starting the server, create the local storage paths and run the init subcommand to bootstrap the database and configuration files.

Create the directory structure and initialize:

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

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

The init command, implemented in crates/ai-memory-cli/src/main.rs, creates three critical components:

• ~/.local/share/ai-memory/data.sqlite – The SQLite database with FTS5 and embedding support
• ~/.local/share/ai-memory/wiki/ – A plain-text markdown wiki directory compatible with git versioning
• ~/.config/ai-memory/config.toml – Server configuration including bind addresses and host policies

By default, the configuration binds to 127.0.0.1:49374 and requires no authentication for local development.

Start the Memory Server

Launch the server using the serve subcommand to begin listening for MCP requests and web interface traffic.

Run the server in the foreground:

./target/release/ai-memory serve \
  --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml \
  --bind 127.0.0.1:49374 \
  --enable-web

The server enforces a single-writer actor invariant for the SQLite store, meaning the binary acts as the exclusive writer to prevent corruption. As documented in AGENTS.md, this architecture ensures ACID compliance while allowing multiple agent clients to query memory concurrently.

Wire Up a Coding Agent (Claude Code Example)

Register the binary with your coding agent using the install-mcp and install-hooks subcommands to capture prompts and tool outputs automatically.

Generate an authentication token and install the MCP configuration:

# Optional: create a bearer token for non-localhost deployments

TOKEN=$(./target/release/ai-memory generate-auth-token)

# Register with Claude Code

./target/release/ai-memory install-mcp \
  --client claude-code \
  --apply

# Install lifecycle hooks to capture session data

./target/release/ai-memory install-hooks \
  --agent claude-code \
  --apply

The install-mcp command writes the MCP server definition to $HOME/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json), enabling tools like memory_query and memory_handoff_accept. The install-hooks command stages native binaries under ~/.local/share/ai-memory/hooks/claude-code/ that intercept every prompt and tool call, respecting the capture policies defined in the source code as outlined in docs/install.md.

Optional: Run as a systemd Service

For a hands-off deployment, install ai-memory via the Arch Linux AUR and manage it as a user-level systemd service.

Install using an AUR helper:

# Option 1: Pre-built binary

yay -S ai-memory-bin

# Option 2: Build from source

yay -S ai-memory

Enable the service to start on boot:

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

The systemd unit reads from ~/.config/ai-memory/config.toml and stores data in ~/.local/share/ai-memory, matching the manual installation layout documented in docs/install.md.

Verify the installation by querying the health endpoint:

curl http://127.0.0.1:49374/mcp
ai-memory status

Summary

• ai-memory compiles to a single Rust binary via cargo build --release -p ai-memory-cli using the toolchain specified in rust-toolchain.toml
• The init subcommand creates a self-contained data directory with SQLite storage and markdown wiki under ~/.local/share/ai-memory
• The serve subcommand starts the HTTP server on 127.0.0.1:49374 with optional web UI via --enable-web
• MCP registration for agents like Claude Code uses install-mcp and install-hooks to enable automatic memory capture
• Native systemd integration is available through AUR packages ai-memory-bin or ai-memory

Frequently Asked Questions

What Rust version is required to compile ai-memory?

The repository pins the compiler version in rust-toolchain.toml to Rust 1.95 or newer. Running rustup show in the project directory automatically installs the correct toolchain edition specified in that file.

Where does ai-memory store data when running as a binary?

By default, the binary uses ~/.local/share/ai-memory for the SQLite database and markdown wiki, and ~/.config/ai-memory/config.toml for server settings. These paths are configurable via the --data-dir and --config flags on every subcommand.

How do I integrate ai-memory with Claude Code without using Docker?

Run ai-memory install-mcp --client claude-code --apply to register the Model Context Protocol server, then run ai-memory install-hooks --agent claude-code --apply to capture session data. These commands modify $HOME/.claude.json and install hook binaries that require no container runtime.

Can the ai-memory binary run as a background service?

Yes. The ai-memory binary supports running under systemd via the AUR packages. Use systemctl --user enable --now ai-memory.service to run it as a user-level daemon that starts automatically and manages the lifecycle of the SQLite-backed memory server.

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