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

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.

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, 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.

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, 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 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 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 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, 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, 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 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 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.

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

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