# Understanding the ai-memory Crate Layout: A Complete Guide to the 9-Crate Workspace

> Explore the ai-memory Rust workspace and its 9-crate layout. Understand each crate's purpose from domain types to LLM abstractions and learn about its SQLite actor and atomic wiki write guarantees.

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

---

**The ai-memory project implements a Rust workspace with nine specialized crates where each crate isolates a single responsibility—from pure domain types and SQLite persistence to LLM abstractions and MCP protocol handling—unified by a single-writer SQLite actor and atomic wiki write guarantees.**

The **ai-memory** repository by AkitaOnRails employs a sophisticated multi-crate architecture designed for AI memory management. Understanding the **ai-memory crate layout** is essential for developers contributing to the system, as each crate enforces strict architectural boundaries while maintaining cross-cutting invariants like the three-tuple identity model and the markdown-as-source-of-truth hierarchy.

## Overview of the ai-memory Crate Layout

The workspace organizes nine specialized crates under the top-level `crates/` directory. This modular approach ensures that domain logic remains separate from I/O operations, storage concerns remain isolated from transport protocols, and the command-line interface composes all underlying functionality into a cohesive user experience.

```text
crates/
├── ai-memory-core/
├── ai-memory-store/
├── ai-memory-wiki/
├── ai-memory-mcp/
├── ai-memory-hooks/
├── ai-memory-llm/
├── ai-memory-consolidate/
├── ai-memory-workstream/
└── ai-memory-cli/

```

## Foundation Crate: ai-memory-core

The **ai-memory-core** crate serves as the foundation for all other crates, containing only domain vocabulary and types with **no I/O operations**. This constraint ensures that core business logic remains pure and easily testable across the workspace.

Located in [`crates/ai-memory-core/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/lib.rs), this crate defines essential identifiers like `PageId` and `ObservationId`, error types, and privacy-stripping logic through the `Sanitized` wrapper. Any crate requiring domain primitives depends on this foundational layer.

```rust
use ai_memory_core::{NewObservation, ObservationKind, Sanitizer};

let raw = r#"User asked: "What is the crate layout?" "#;
let sanitized = Sanitizer::default()
    .sanitize(raw, ObservationKind::UserPrompt)
    .expect("sanitization failed");

```

## Persistence Layer Crates

The architecture separates storage concerns into two complementary crates that maintain the invariant that markdown files serve as the **single source of truth** while SQLite acts as a derived index.

### ai-memory-store (SQLite Layer)

**ai-memory-store** implements the SQLite persistence layer, housing the **single-writer SQLite actor** that serializes all database mutations. This crate manages the read-only connection pool, decay mathematics for memory prioritization, and all schema-related queries for wiki pages, observations, sessions, and embeddings.

The core implementation resides in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs), where the writer actor ensures that all mutations respect the three-tuple identity model while preventing concurrent write conflicts.

### ai-memory-wiki (File System Layer)

**ai-memory-wiki** handles **atomic markdown file operations**, including the file-watcher implementation and git integration. This crate guarantees that the wiki directory remains the single source of truth, implementing atomic write operations that ensure consistency even during system failures.

Key source files include [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) and the file-watcher implementation that monitors directory changes for synchronization with the SQLite index.

## Interface and Protocol Crates

These crates handle external communication, converting between external protocols and internal domain types while enforcing authentication and admission chains.

### ai-memory-mcp (MCP Transport)

**ai-memory-mcp** implements the RMCP (Remote Model Context Protocol) transport layer and tool-router. It exposes **18 MCP tools** including `memory_query` and `memory_write_page`, while enforcing authentication, scope resolution, and admission chains.

The implementation in [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs) routes incoming requests to the appropriate storage and wiki operations while maintaining security boundaries.

### ai-memory-hooks (HTTP Endpoints)

**ai-memory-hooks** provides the HTTP `/hook` endpoint for receiving lifecycle hooks. This crate defines payload schemas and sanitization logic, converting raw JSON into sanitized `Observation` types that flow into the storage layer.

The router implementation in [`crates/ai-memory-hooks/src/router.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/router.rs) handles the transformation and validation of incoming webhook data before it reaches the domain layer.

### ai-memory-llm (Provider Abstractions)

**ai-memory-llm** offers provider-agnostic abstractions for language models and embedding services. It defines the `LlmProvider` and `Embedder` traits, plus authentication handling for Anthropic, OpenAI, Gemini, and Copilot.

Located in [`crates/ai-memory-llm/src/provider.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-llm/src/provider.rs), this crate allows the consolidation and query pipelines to remain independent of specific vendor APIs.

## Processing and Workflow Crates

These crates implement specific business logic pipelines for memory management and session handling.

### ai-memory-consolidate (Memory Pipeline)

**ai-memory-consolidate** implements a Karpathy-style **ingest, lint, sweep, and auto-improve pipeline**. This crate takes finished sessions, runs LLM-driven consolidation processes, and stages edits through the standard wiki write path.

The pipeline logic resides in [`crates/ai-memory-consolidate/src/consolidator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/consolidator.rs), coordinating between the LLM providers and wiki storage to optimize memory organization.

### ai-memory-workstream (Transcript Handling)

**ai-memory-workstream** manages read-only native transcript handling and launch adapters for the `ai-memory run` command. It provides the managed work-stream ledger used for cross-harness continuity and session tracking.

The implementation in [`crates/ai-memory-workstream/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/lib.rs) ensures that transcript data remains accessible for consolidation while maintaining immutability guarantees.

## User Interface Crate

### ai-memory-cli (Binary Entry Point)

**ai-memory-cli** serves as the end-user binary, providing the `ai-memory` command-line interface. This crate parses CLI flags, loads configuration files, and forwards calls to the underlying library crates, implementing all sub-commands including `search`, `write-page`, and `auto-improve`.

The entry point in [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs) composes the entire crate ecosystem into a unified user experience.

## Architectural Invariants Across the ai-memory Crate Layout

Several critical invariants bind the **ai-memory crate layout** together across crate boundaries:

- **Single-Writer SQLite Actor**: Located exclusively in `ai-memory-store`, this actor serializes all database mutations to prevent race conditions while maintaining the derived index.
- **Source of Truth Hierarchy**: The `ai-memory-wiki` crate owns atomic file operations, ensuring markdown files remain authoritative while SQLite serves as a queryable cache.
- **Three-Tuple Identity**: All crates respect the identity model defined in `ai-memory-core` when referencing memory entities across the system.
- **I/O Isolation**: Only specific crates (`ai-memory-store`, `ai-memory-wiki`, `ai-memory-hooks`, `ai-memory-mcp`, `ai-memory-cli`) perform I/O, while core and processing crates remain pure.

## Summary

- The **ai-memory** workspace consists of nine specialized crates under `crates/`, each with a single, well-defined responsibility.
- **ai-memory-core** provides pure domain types without I/O, serving as the type foundation for all other crates in the workspace.
- **ai-memory-store** and **ai-memory-wiki** implement the dual-layer persistence strategy with atomic file operations and a single-writer SQLite actor ensuring data consistency.
- **ai-memory-mcp** and **ai-memory-hooks** handle external protocol interfaces while **ai-memory-llm** abstracts provider-specific implementations for Anthropic, OpenAI, and others.
- **ai-memory-consolidate** and **ai-memory-workstream** implement business logic pipelines for memory optimization and transcript management.
- **ai-memory-cli** composes all crates into the final user-facing binary at [`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs).

## Frequently Asked Questions

### What is the purpose of ai-memory-core?

**ai-memory-core** contains the domain vocabulary, identifiers, and privacy-stripping logic used throughout the system. It performs no I/O operations, making it a pure foundation that other crates depend on for types like `PageId` and `Sanitized`. This separation ensures that business logic remains testable and independent of storage mechanisms or network concerns.

### How does ai-memory-store differ from ai-memory-wiki?

While **ai-memory-store** manages the SQLite database layer including the single-writer actor and decay mathematics, **ai-memory-wiki** handles atomic markdown file operations and git integration. The wiki crate ensures that markdown files serve as the single source of truth, while the store maintains a derived index in SQLite for efficient querying and relationship mapping.

### Which crate should I modify to add new MCP tools?

New MCP tools should be added to **ai-memory-mcp**, specifically within the tool-router implementation in [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs). This crate exposes the 18 existing tools and enforces authentication, scope resolution, and admission chains before routing requests to the underlying storage layers.

### Where is LLM provider configuration handled in the ai-memory crate layout?

**ai-memory-llm** in [`crates/ai-memory-llm/src/provider.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-llm/src/provider.rs) contains the provider-agnostic abstractions including `LlmProvider` and `Embedder` traits, plus authentication handling for Anthropic, OpenAI, Gemini, and Copilot. This allows the consolidation pipeline to work with multiple LLM backends without vendor lock-in.