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

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.

Simultaneously, the wiki layer in 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. 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:

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:

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

Configure Environment Variables

Point the CLI to your server instance:

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:

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

Install lifecycle hooks to capture agent events:

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

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

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

Project Resolution and Verification

Configure consistent project identification across subdirectories:

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

Verify server connectivity:

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:

claude-code

Inside the agent session, query accumulated knowledge:

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

> 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 – CLI entry point and subcommand parsing
• crates/ai-memory-store/src/lib.rs – SQLite storage with single-writer actor pattern
• crates/ai-memory-wiki/src/lib.rs – Atomic markdown operations and Git integration
• crates/ai-memory-mcp/src/lib.rs – RMCP transport layer and tool registration
• docs/ARCHITECTURE.md – Data flow diagrams and system invariants
• docs/install.md – Detailed installation procedures
• docs/marker-file.md – Configuration for .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. All write operations serialize through a single SQLite connection, while reads use connection pooling. Markdown writes in 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.

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