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

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:

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, so Cargo automatically selects the correct version once installed.

---

Build and Install ai-memory

Clone the repository and compile the binary:

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

For system-wide installation:

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, which wires together the MCP server, HTTP API, and wiki subsystem.

---

Configure Your ai-memory Instance

Create a .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:

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

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

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

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.

Override the default data directory:

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:

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

Expected output:

{"status":"ok"}

Execute the full test suite to validate your installation:

TAILWIND_SKIP=1 cargo test --workspace

CI pipeline steps in .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

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

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	Binary entry point
crates/ai-memory-core/src/config.rs	Configuration loading (Config::load)
crates/ai-memory-store/src/lib.rs	SQLite store with single-writer guarantees
crates/ai-memory-wiki/src/lib.rs	Atomic markdown operations
hooks/	Agent lifecycle integration
docs/install.md	Official installation documentation
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 at project root; Config::load() in 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 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 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 bind address matches your agent's MCP URL. Review ai-memory-core/src/config.rs for scope resolution rules that might restrict certain client operations.

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