# How to Set Up ai-memory for Cross-Session AI Agent Memory

> Learn to set up ai-memory for cross-session AI agent memory. This Rust service provides persistent, searchable wiki with SQLite for seamless memory continuity across CLI sessions and machines.

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

---

**ai-memory is a Rust-based service that provides coding agents like Claude Code, Codex, and OpenCode with a persistent, searchable wiki backed by SQLite, enabling seamless memory continuity across CLI sessions and different machines through MCP tools and lifecycle hooks.**

Setting up cross-session AI agent memory requires a robust backend that can capture, store, and retrieve context beyond a single terminal instance. ai-memory, developed by akitaonrails/ai-memory, solves this by implementing a **markdown-first wiki architecture** synchronized with SQLite, allowing AI agents to maintain knowledge across multiple sessions, IDE plugins, and even different development machines.

## Understanding the Core Architecture

### Data Flow and Storage Layers

The system captures agent lifecycle events through hooks (e.g., `session-start`, `post-tool-use`) and POSTs them to the server's `/hook` endpoint. A **sanitizer** processes and caps the payload before handing it to a **single-writer SQLite actor** that stores observations in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs).

Simultaneously, the **wiki layer** in [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) atomically updates markdown pages in `<data_dir>/wiki/` using `Wiki::write_page`, which employs atomic tmp + rename + fsync patterns to ensure consistency. The SQLite database serves as a derived index with FTS5 full-text search (`pages_fts`) and optional vector embeddings (`page_embeddings`), while the markdown files remain the authoritative source of truth.

### Cross-Session Continuity Mechanism

When a session terminates, the server synthesizes a summary page at `sessions/<id>.md` and creates a **handoff** record. The next agent instance—even on a different machine or client—automatically receives pending handoffs on the subsequent `session-start` event. This eliminates the need to manually copy context between CLI processes or editor windows.

### MCP Tool Integration

Agents communicate with ai-memory via JSON-RPC over HTTP at the `/mcp` endpoint. The system exposes 18 tools including `memory_query`, `memory_write_page`, and `memory_handoff_accept`, implemented in [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs). These tools are automatically registered in agent configurations through the `ai-memory install-mcp` command, bridging the gap between agent runtimes and the persistent store.

## Installation and Configuration

### Deploy the Server

Start the ai-memory server using Docker to ensure consistent networking and storage:

```bash
docker run -d --name ai-memory \
  -p 0.0.0.0:49374:49374 \
  -v ai-memory-data:/data \
  akitaonrails/ai-memory:latest

```

For remote access, generate an authentication token and configure security:

```bash
export TOKEN=$(docker run --rm akitaonrails/ai-memory:latest generate-auth-token)

```

### Configure Environment Variables

Point the CLI to your server instance:

```bash
export AI_MEMORY_SERVER_URL="http://<host-ip>:49374"
export AI_MEMORY_AUTH_TOKEN="$TOKEN"

```

### Install MCP Tools and Hooks

Register the MCP tools with your preferred agent:

```bash
ai-memory install-mcp --client claude-code --apply

```

Install lifecycle hooks to capture agent events:

```bash
ai-memory install-hooks --agent claude-code --apply

```

For per-session scoping support, enable the session-aware MCP bridge:

```bash
ai-memory install-mcp --client claude-code --session-aware --apply

```

### Project Resolution and Verification

Configure consistent project identification across subdirectories:

```bash
ai-memory install-hooks --apply --agent claude-code --project-strategy repo-root

```

Verify server connectivity:

```bash
curl http://127.0.0.1:49374/mcp

```

A JSON-RPC error response confirms the endpoint is reachable.

## Daily Usage and Workflow

Once configured, start your agent normally:

```bash
claude-code

```

Inside the agent session, query accumulated knowledge:

```bash
> memory_query "how does the auto-improve scheduler work?"

```

The system returns LLM-enhanced answers with citations to specific markdown pages in the wiki. When finishing work, simply exit—the server automatically creates a handoff record. Resume in any client by calling:

```bash
> memory_handoff_accept

```

Additional CLI utilities include:

- `ai-memory status` – Display server health and configuration
- `ai-memory write-page path="decisions/001.md" body="..."` – Manual knowledge entry
- `ai-memory finalize-session --agent claude-code` – Explicit session closure for agents lacking native `session-end` hooks
- `ai-memory backup --to ~/backup.tar.gz` – Online SQLite backup without downtime

## Key Implementation Files

Understanding the source structure helps with advanced customization:

- [`crates/ai-memory-cli/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/lib.rs) – CLI entry point and subcommand parsing
- [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) – SQLite storage with single-writer actor pattern
- [`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 and Git integration
- [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs) – RMCP transport layer and tool registration
- [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) – Data flow diagrams and system invariants
- [`docs/install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md) – Detailed installation procedures
- [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) – Configuration for [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker files

## Summary

- **ai-memory** provides persistent cross-session memory for AI coding agents through a Rust-based server and SQLite-backed markdown wiki.
- The architecture maintains **atomic consistency** between markdown files and database indices using single-writer patterns in `crates/ai-memory-store`.
- **MCP tools** like `memory_query` and `memory_handoff_accept` enable agents to read from and write to the shared knowledge base.
- Setup requires **Docker deployment**, environment variable configuration, and installation of hooks and MCP configs via the `ai-memory` CLI.
- **Handoff records** automatically transfer context between different clients, machines, and CLI sessions without manual intervention.

## Frequently Asked Questions

### Does ai-memory require an LLM provider to function?

No. While configuring `AI_MEMORY_LLM_PROVIDER` enables features like `memory_consolidate` and `auto_improve` for intelligent rewriting of summary pages, the system operates fully without any provider. The core storage, search, and handoff mechanisms work independently using SQLite and FTS5 indexing.

### How does ai-memory handle concurrent writes from multiple agents?

The system enforces a **single-writer invariant** through an actor pattern implemented in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs). All write operations serialize through a single SQLite connection, while reads use connection pooling. Markdown writes in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) use atomic filesystem operations (tmp + rename + fsync) to prevent corruption during concurrent access.

### Can I use ai-memory across different machines?

Yes. Deploy the Docker container on a network-accessible host, configure `AI_MEMORY_SERVER_URL` with the host IP, and set `AI_MEMORY_AUTH_TOKEN` for security. The server binds to all interfaces (`0.0.0.0:49374`) by default when deployed via Docker, allowing any configured client to connect and share the same persistent memory regardless of physical location.

### What agents are supported by ai-memory?

The system supports Claude Code, Codex, OpenCode, and other MCP-compatible agents. The `ai-memory install-mcp` and `ai-memory install-hooks` commands provide specific integrations for each agent, with fallback script-based hooks for agents lacking native lifecycle event support. Refer to `README.md#support-matrix` in the repository for the complete compatibility list.