What Is the Underlying Technology Stack for ai-memory?

The ai-memory project is a pure-Rust workspace leveraging Tokio for asynchronous I/O, SQLite for embedded persistence, Axum for web serving, and optional Candle-based LLM inference, organized into single-responsibility crates that enforce memory safety and zero-unsafe-code guarantees.

The akitaonrails/ai-memory repository implements a comprehensive AI memory system using modern Rust architecture. Built with the 2024 edition toolchain and pinned to compiler version 1.95, the underlying technology stack for ai-memory prioritizes reproducible builds, type safety, and clear separation of concerns. The project operates as a Cargo workspace containing ten specialized crates, each handling distinct domains from low-level storage to HTTP API exposure.

Core Language and Build Configuration

The foundation rests on Rust 2024 edition with the compiler version strictly pinned in rust-toolchain.toml. This guarantees reproducible builds across development environments while leveraging modern language features. The workspace-wide Cargo.toml enforces strict linting rules including unsafe_code = "forbid" and missing_docs = "warn", ensuring every crate maintains documentation standards and memory safety without unsafe blocks.

Asynchronous Runtime and Web Layer

Tokio with full features powers all I/O-bound operations throughout the system. The web server stack combines Axum for HTTP routing, Tower and tower-http for middleware, and the rmcp MCP SDK for Model Context Protocol integration. This combination exposes endpoints at /api/v1, /admin/*, and /web while handling both human-facing interfaces and machine-readable MCP bridges.

In crates/ai-memory-cli/src/main.rs, the entry point initializes the runtime:

// Run the binary: `ai-memory serve`
use ai_memory_cli::run_serve;
#[tokio::main]
async fn main() {
    // Serve the HTTP/MCP API; binds to loopback by default.
    run_serve().await.unwrap();
}

Database Persistence and SQLite Architecture

SQLite serves as the embedded database, accessed through the bundled rusqlite crate with FTS5 enabled for full-text search. The ai-memory-store crate implements a single-writer actor pattern where all database writes funnel through a dedicated thread via an mpsc channel, preventing N+1 queries and ensuring transactional consistency. Migrations are handled by refinery.

Every database row utilizes scope-resolved IDs keyed by (workspace_id, project_id, path), guaranteeing multi-user and multi-session isolation. The store implementation in crates/ai-memory-store/src/lib.rs manages the SQLite writer actor, reader connection pools, and decay mathematics for memory prioritization.

File System Integration and Git Versioning

For wiki functionality, the stack employs notify and notify-debouncer-full for filesystem watching, combined with git2 (vendored libgit2) for atomic markdown writes and versioning. The ai-memory-wiki crate handles atomic file operations by writing to temporary files, renaming them into place, and issuing fsync calls, while the watcher explicitly ignores its own writes to prevent feedback loops.

CLI operations leverage this layer for atomic updates:

# Add a page to the wiki (writes atomically and updates the DB)

ai-memory wiki write-page --path notes/todo.md --content "• Finish docs"

Optional LLM and Embedding Engine

The ai-memory-llm crate provides optional large-language-model integration through pure-Rust inference libraries. When enabled, the system uses candle-core, candle-nn, and candle-transformers for on-device inference, plus tokenizers for text processing. HTTP-based providers asynchronously communicate via reqwest with rustls-tls-native-roots.

Critically, ai-memory operates under a zero-LLM default architecture—the system functions fully without any LLM provider. When embedding generation is required, the Embedder trait in crates/ai-memory-llm/src/lib.rs abstracts over local and remote providers:

use ai_memory_llm::{Embedder, ProviderAuth};

#[tokio::main]
async fn main() {
    // Example using the built‑in Candle provider (no external binary)
    let auth = ProviderAuth::from_env(); // reads AI_MEMORY_… vars
    let embedder = Embedder::new(auth).await.unwrap();
    let vectors = embedder.embed("Explain the Rust ownership model").await.unwrap();
    println!("{:?}", vectors);
}

Configuration, Security, and Observability

Configuration management combines figment (supporting TOML and environment variables) with clap 4 for command-line parsing and shell completions via clap-complete. Security relies on secrecy for secret handling, subtle for constant-time comparisons, argon2 for password hashing, and getrandom for cryptographic randomness.

Structured logging uses the tracing ecosystem (tracing, tracing-subscriber, tracing-appender) to output JSON-compatible logs. Time handling utilizes jiff for date-time operations, while uuid generates v4/v5/v7 identifiers for entities.

Workspace Crate Organization

The technology stack divides functionality across ten workspace members defined in the root Cargo.toml:

• ai-memory-core – Domain types, errors, and ID implementations without I/O dependencies
• ai-memory-store – SQLite writer actor, reader pools, and query primitives
• ai-memory-wiki – Atomic markdown operations, file watching, and Git integration
• ai-memory-mcp – MCP transport layer, tool routing, and administrative routes
• ai-memory-hooks – Payload sanitization and schema validation for external hooks
• ai-memory-llm – Provider abstractions (LlmProvider, Embedder) for inference
• ai-memory-consolidate – Auto-improvement pipelines for memory consolidation
• ai-memory-web – Read-only web UI and JSON API endpoints
• ai-memory-cli – Command-line binary entry point
• ai-memory-workstream – Native transcript handling and launch adapters

Reading persisted data through the store layer demonstrates the clean API design:

use ai_memory_store::Store;

#[tokio::main]
async fn main() {
    let store = Store::open_default().await.unwrap();
    let page = store.get_page("notes/todo.md").await.unwrap();
    println!("{}", page.content);
}

Summary

• ai-memory is built as a Rust 2024 edition workspace with compiler version 1.95 pinned for reproducibility.
• Tokio and Axum power the asynchronous runtime and HTTP/MCP server layers.
• SQLite with rusqlite provides embedded persistence using a single-writer actor pattern to prevent race conditions.
• Candle and tokenizers enable optional on-device LLM inference without requiring external binaries.
• The codebase enforces unsafe_code = "forbid" and organizes functionality into ten single-responsibility crates spanning core types, storage, wiki operations, and CLI interfaces.

Frequently Asked Questions

What database does ai-memory use for persistence?

The system uses SQLite accessed through the rusqlite crate with bundled libraries and FTS5 full-text search enabled. The ai-memory-store crate implements a dedicated writer thread with mpsc channel communication to serialize all writes, ensuring transactional consistency while allowing concurrent reads through a connection pool.

Can ai-memory function without connecting to external LLM APIs?

Yes. The architecture follows a zero-LLM default principle where the system operates fully without any LLM provider. Optional local inference is available through the Candle ecosystem (candle-core, candle-transformers) for pure-Rust, on-device embedding generation, while remote providers can be configured via the ai-memory-llm crate abstraction layer.

How does the project handle concurrent file writes to the wiki?

The ai-memory-wiki crate implements atomic file writes by creating temporary files, renaming them to target paths, and calling fsync before closing. The notify filesystem watcher ignores writes initiated by the application itself, preventing feedback loops while detecting external modifications. git2 provides atomic commits for versioning.

What Rust version is required to build ai-memory?

The project requires Rust 1.95 or later, strictly pinned via rust-toolchain.toml to ensure reproducible builds across environments. The codebase targets the 2024 edition and enforces workspace-wide lints including unsafe_code = "forbid", making it compatible with any platform supporting standard Rust toolchain installations.

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