# What Is the ai-memory-wiki Crate? Responsibilities, Architecture, and Code Examples

> Discover the ai-memory-wiki crate's role in synchronizing your markdown filesystem with SQLite for efficient indexing and search. Learn its core responsibilities and architecture.

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

---

**The `ai-memory-wiki` crate is the wiki filesystem layer of ai-memory that treats the on-disk markdown tree as the single source of truth while keeping it synchronized with the SQLite store for indexing and search.**

The `ai-memory-wiki` crate sits at the heart of the [akitaonrails/ai-memory](https://github.com/akitaonrails/ai-memory) repository, bridging raw markdown files on disk with the database layer. It ensures every page write, move, or deletion remains **atomic, consistent, and immediately indexed**. This article breaks down the crate's core responsibilities, key source files, and practical usage patterns.

## Core Responsibilities of the ai-memory-wiki Crate

The crate operates as a **write-through filesystem abstraction** with ten primary responsibilities:

### 1. Atomic Markdown Writes

All file writes use a **tmp + rename + fsync** pattern to prevent data loss during crashes. The `write_atomic` function in [`src/atomic.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/atomic.rs) implements this safety guarantee.

### 2. Front-Matter Handling

The crate parses, emits, and derives titles from YAML front-matter via [`src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/markdown.rs), preserving comments and key ordering for human-editable files.

### 3. Write-Through to the Store

Every public mutation—`write_page`, `move_project_workspace`, `delete_page`—calls the `WriterHandle` actor to upsert the corresponding SQLite row. The database index never diverges from the filesystem state.

### 4. Scope-Aware Directory Layout

Pages follow a strict hierarchy:

```

<wiki_root>/<workspace_id>/<project_id>/<page_path>

```

Helpers like `project_root` and `abs_path` enforce this layout consistently.

### 5. Admissions and Webhooks

The optional `AdmissionChain` (configured via `with_admission_chain`) can mutate or reject writes before they commit through `preflight_admission` hooks.

### 6. Git Integration

[`src/git.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/git.rs) initializes a git repository in the wiki root, providing `commit_all`, checkpoint handling, and page restoration from historical checkpoints.

### 7. Filesystem Watcher and Reconciliation

The `WatcherHandle` monitors the tree for external changes and triggers re-indexing. Functions like `move_project_workspace` coordinate exclusive locks to prevent stale writes during moves.

### 8. Scope Manifests

On first write to any scope, `ensure_scope_manifests` creates [`_meta.md`](https://github.com/akitaonrails/ai-memory/blob/main/_meta.md) files so projects can be rebuilt without server restarts.

### 9. Auto-Improvement Sidecars

Helper functions `write_auto_improve_sidecar` and `approve_auto_improve_proposal` manage AI-generated proposal artifacts stored alongside—but not indexed with—the main wiki tree.

### 10. Safe Deletion and Decay

`delete_page`, `evict_page_if_latest`, and `hard_delete_decay_tombstone` handle removal with proper tombstone management for the decay system.

## Key Source Files and Their Roles

Understanding the `ai-memory-wiki` crate requires familiarity with its core modules:

| File | Responsibility |
|------|----------------|
| [`src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/lib.rs) | Public re-exports and crate entry point |
| [`src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/wiki.rs) | Main `Wiki` struct with high-level operations |
| [`src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/markdown.rs) | Front-matter-aware parser, emitter, link extraction |
| [`src/atomic.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/atomic.rs) | Safe atomic file writes |
| [`src/git.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/git.rs) | Git repository management, commits, checkpoints |
| [`src/watcher.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/watcher.rs) | Filesystem watcher for change detection |
| [`src/admission.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/admission.rs) | Webhook chain definition and processing |
| `src/migrations/` | Database migration runner for wiki schema |

## Code Examples: Working with ai-memory-wiki

### Initialize a Wiki Handle and Write a Page

```rust
use ai_memory_wiki::Wiki;
use ai_memory_store::WriterHandle;
use std::path::Path;

// WriterHandle created elsewhere in the application stack
let writer: WriterHandle = /* … */;

// Initialize wiki at <data_dir>/wiki
let wiki = Wiki::new(Path::new("/var/lib/ai-memory"), writer)?;

// Construct markdown with front-matter
let markdown = ai_memory_wiki::Markdown {
    frontmatter: serde_json::json!({ "title": "My First Page" }),
    body: "Hello, world!".into(),
};

// Atomic write; WriterHandle upserts the DB row automatically
let page_id = wiki
    .write_page(
        workspace_id,
        project_id,
        PagePath::new("notes/hello.md")?,
        markdown,
        None, // no admission context
        None, // no author
    )
    .await?;
println!("Created page with ID {page_id}");

```

Source: `Wiki::new` and `Wiki::write_page` in [[`src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/wiki.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs).

### Move a Project Between Workspaces

```rust
// Relocate entire project with all its pages
let outcome = wiki
    .move_project_workspace(proj_id, ws_from, ws_to, None)
    .await?;
println!("Moved {} pages", outcome.pages_moved);

```

Source: `move_project_workspace` in [[`src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/wiki.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs).

### Commit the Wiki Tree to Git

```rust
// Create checkpoint of entire wiki state
let commit_oid = wiki.commit_all("Periodic backup")?.expect("nothing to commit");
println!("Created git commit {}", commit_oid);

```

Source: `commit_all` in [[`src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/wiki.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs).

### Enable Admission Webhook Validation

```rust
let chain = AdmissionChain::new(vec![/* webhook configurations */]);
let wiki = wiki.with_admission_chain(chain);

```

Source: `with_admission_chain` in [[`src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/lib.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs).

### Parse and Emit Markdown with Front-Matter

```rust
let raw = "---\ntitle: Sample\n---\nThis is the body.\n";

// Parse into structured representation
let md = ai_memory_wiki::parse(raw)?;

// Round-trip back to string preserving formatting
let emitted = ai_memory_wiki::emit(&md)?;
assert_eq!(raw, emitted);

```

Source: `parse` and `emit` in [[`src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/markdown.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/markdown.rs).

## Summary

- **Primary role**: The `ai-memory-wiki` crate maintains the markdown filesystem as the **authoritative source of truth** for ai-memory's knowledge base.
- **Consistency guarantee**: Every write operation is **atomic on disk** and **synchronously reflected in SQLite** via the `WriterHandle` actor.
- **Key capabilities**: Front-matter handling, git versioning, admission webhooks, filesystem watching, and safe deletion with decay tombstones.
- **Critical files**: [`src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/wiki.rs) for operations, [`src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/markdown.rs) for content handling, [`src/atomic.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/atomic.rs) for write safety, [`src/git.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/git.rs) for version control.

## Frequently Asked Questions

### What makes ai-memory-wiki different from a simple file writer?

The `ai-memory-wiki` crate combines **atomic filesystem operations** with **synchronous database updates** through the `WriterHandle` actor. Unlike standalone file utilities, it guarantees that the SQLite index never diverges from the markdown tree—every `write_page` call both persists to disk and upserts the corresponding row for search and retrieval.

### How does ai-memory-wiki handle concurrent writes to the same page?

The crate uses **exclusive mutation locks** through functions like `move_project_workspace` and `move_session_page`, which coordinate access to prevent stale writes. The `WatcherHandle` additionally reconciles any external filesystem changes by triggering re-indexing when it detects modifications outside the application.

### Can ai-memory-wiki reject or modify writes before they complete?

Yes, through the **`AdmissionChain`** mechanism defined in [`src/admission.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/admission.rs). By calling `with_admission_chain`, you can inject webhooks or validation logic that runs during `preflight_admission`—either mutating the content or rejecting the operation entirely before any filesystem or database changes occur.

### Does ai-memory-wiki require a running server to maintain project metadata?

No. The `ensure_scope_manifests` function automatically creates [`_meta.md`](https://github.com/akitaonrails/ai-memory/blob/main/_meta.md) files on first write to any scope. These manifests allow the system to **rebuild project state from the filesystem alone** without requiring a server restart or database inspection.