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

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 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 implements this safety guarantee.

2. Front-Matter Handling

The crate parses, emits, and derives titles from YAML front-matter via 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 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 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	Public re-exports and crate entry point
src/wiki.rs	Main Wiki struct with high-level operations
src/markdown.rs	Front-matter-aware parser, emitter, link extraction
src/atomic.rs	Safe atomic file writes
src/git.rs	Git repository management, commits, checkpoints
src/watcher.rs	Filesystem watcher for change detection
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

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/crates/ai-memory-wiki/src/wiki.rs).

Move a Project Between Workspaces

// 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/crates/ai-memory-wiki/src/wiki.rs).

Commit the Wiki Tree to Git

// 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/crates/ai-memory-wiki/src/wiki.rs).

Enable Admission Webhook Validation

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/crates/ai-memory-wiki/src/lib.rs).

Parse and Emit Markdown with Front-Matter

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/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 for operations, src/markdown.rs for content handling, src/atomic.rs for write safety, 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. 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 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.

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