# What Is the Underlying Technology Stack for ai-memory?

> Explore the ai-memory technology stack. Discover how Rust, Tokio, Axum, and SQLite power this efficient project, ensuring memory safety and robust performance.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: internals
- Published: 2026-09-11

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/rust-toolchain.toml). This guarantees reproducible builds across development environments while leveraging modern language features. The workspace-wide [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs), the entry point initializes the runtime:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-llm/src/lib.rs) abstracts over local and remote providers:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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.