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

> Install ai-memory as a self-contained Rust binary. Compile from source and run commands to create a native SQLite memory server for coding agents. Full native installation guide.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Compile ai-memory from source using the pinned Rust toolchain in [`rust-toolchain.toml`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/Cargo.toml) and pins the required compiler version in [`rust-toolchain.toml`](https://github.com/akitaonrails/ai-memory/blob/main/rust-toolchain.toml) to ensure reproducible builds.

Install the Rust toolchain and compile the release binary:

```bash

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash
./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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md).

Verify the installation by querying the health endpoint:

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.