# How to Set Up ai-memory for AI Coding Agents: A Complete Installation Guide

> Install ai-memory for AI coding agents and give them long-term, cross-session memory. This Rust binary is easy to build, configure, and deploy in minutes. Get started now.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: getting-started
- Published: 2026-09-01

---

**ai-memory provides AI coding agents with long-term, cross-session memory through a self-contained Rust binary that you can build, configure, and deploy in minutes.**

Setting up ai-memory for your AI coding agents involves installing the Rust toolchain, compiling the project, creating a local configuration file, and connecting your agents to the MCP endpoint. This guide walks through each step using the actual implementation details from the akitaonrails/ai-memory repository.

---

## Prerequisites: Rust Toolchain and Git

Before building ai-memory, you need a recent Rust toolchain (version 1.95 or later) and Git installed on your system.

Install Rust via rustup:

```bash
curl https://sh.rustup.rs -sSf | sh
rustup toolchain install 1.95
rustup default 1.95

```

The project specifies its toolchain in [`rust-toolchain.toml`](https://github.com/akitaonrails/ai-memory/blob/main/rust-toolchain.toml), so Cargo automatically selects the correct version once installed.

---

## Build and Install ai-memory

Clone the repository and compile the binary:

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

```

For system-wide installation:

```bash
cargo install --path .

```

This places the `ai-memory` binary in `$HOME/.cargo/bin`. The entry point lives in [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs), which wires together the MCP server, HTTP API, and wiki subsystem.

---

## Configure Your ai-memory Instance

Create a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file at your project root. This file is read once at startup by `Config::load()` in [`ai-memory-core/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory-core/src/config.rs):

```toml

# .ai-memory.toml

[server]
bind = "127.0.0.1:49374"
auth_token = ""

[store]
path = "data/store.sqlite"

```

- **`bind`** – Loopback address is the safe default for local development.
- **`auth_token`** – Leave empty for local-only use; set for remote deployments.
- **`path`** – SQLite file location used by the store crate.

---

## Start the ai-memory Server

Launch the server with a single command:

```bash
ai-memory

```

The server exposes three main interfaces:

| Interface | URL | Purpose |
|-----------|-----|---------|
| MCP endpoint | `http://127.0.0.1:49374/mcp` | AI agents communicate here |
| Web UI | `http://127.0.0.1:49374/web` | Browse wiki and observations |
| Health API | `http://127.0.0.1:49374/api/v1/health` | Status checks |

The implementation enforces architectural invariants from [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md): single-writer SQLite actor, atomic markdown writes, and strict scope resolution.

---

## Connect Your AI Coding Agents

Point your agent's MCP client to the running server. In your agent configuration:

```toml
[mcp]
url = "http://127.0.0.1:49374/mcp"

```

Supported agents include Codex, Claude Code, Cursor, and any MCP-compatible client. The `ai-memory-hooks` crate provides lifecycle hooks that automatically post sanitized observations to the server when agents execute actions.

---

## Enable LLM-Backed Features (Optional)

For vector embeddings, automatic wiki consolidation, and recall evaluation, configure an LLM provider:

```bash
export AI_MEMORY_OPENAI_API_KEY=sk-...
export AI_MEMORY_PROVIDER=OpenAI

```

The `ai-memory-llm` crate reads these environment variables at startup. Features are documented in [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md).

Override the default data directory:

```bash
AI_MEMORY_DATA_DIR=/tmp/ai-memory-data ai-memory

```

`Config::load()` processes this environment variable before resolving the SQLite path.

---

## Verify Your ai-memory Setup

Run a health check:

```bash
curl -s http://127.0.0.1:49374/api/v1/health | jq

```

Expected output:

```json
{"status":"ok"}

```

Execute the full test suite to validate your installation:

```bash
TAILWIND_SKIP=1 cargo test --workspace

```

CI pipeline steps in [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml) mirror these commands, including formatting checks (`cargo fmt`), linting (`cargo clippy`), and dependency auditing.

---

## Working with ai-memory: Code Examples

### Post Observations Programmatically

```rust
use rmcp::Client;
use ai_memory_hooks::NewObservation;

#[tokio::main]
async fn main() {
    let client = Client::new("http://127.0.0.1:49374/mcp");
    let obs = NewObservation::new("User opened file src/lib.rs".into());
    client.call("store_observation", obs).await.unwrap();
}

```

Observations pass through `ai-memory-hooks` sanitization before persistence in `ai-memory-store`.

### Query Stored Observations via CLI

```bash
ai-memory query --limit 5 --filter "type:observation"

```

The CLI translates this to an MCP `search_observations` call with scoped filters from `ScopeResolver`.

---

## Key Source Files for ai-memory Setup

| File | Purpose |
|------|---------|
| [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs) | Binary entry point |
| [`crates/ai-memory-core/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/config.rs) | Configuration loading (`Config::load`) |
| [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) | SQLite store with single-writer guarantees |
| [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) | Atomic markdown operations |
| `hooks/` | Agent lifecycle integration |
| [`docs/install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md) | Official installation documentation |
| [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) | System invariants and design |

---

## Summary

- **Install Rust 1.95+** via rustup to satisfy build requirements.
- **Build with Cargo** using `cargo build --release` or install globally with `cargo install --path .`.
- **Configure via [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml)** at project root; `Config::load()` in [`ai-memory-core/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory-core/src/config.rs) parses all settings.
- **Start the server** with `ai-memory` to expose MCP, web UI, and health endpoints.
- **Connect agents** to `http://127.0.0.1:49374/mcp` using standard MCP client configuration.
- **Optionally enable LLM features** through environment variables for enhanced memory consolidation.

---

## Frequently Asked Questions

### What Rust version does ai-memory require?

ai-memory requires Rust 1.95 or later. The repository includes [`rust-toolchain.toml`](https://github.com/akitaonrails/ai-memory/blob/main/rust-toolchain.toml) to ensure consistent builds across environments. Run `rustup toolchain install 1.95 && rustup default 1.95` before building.

### Where does ai-memory store its data?

By default, ai-memory uses `data/store.sqlite` relative to the working directory. Override this via the `[store].path` key in [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) or set the `AI_MEMORY_DATA_DIR` environment variable. The `ai-memory-store` crate manages all persistence with single-writer SQLite guarantees.

### Can I run ai-memory without an LLM provider?

Yes. LLM providers are optional and only required for advanced features like vector embeddings and automatic wiki consolidation. Basic observation storage, retrieval, and the web UI function without any API keys configured.

### How do I troubleshoot connection issues between agents and ai-memory?

First verify the server health: `curl http://127.0.0.1:49374/api/v1/health`. Check that your [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) bind address matches your agent's MCP URL. Review [`ai-memory-core/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory-core/src/config.rs) for scope resolution rules that might restrict certain client operations.