How the AI-Memory Wiki's Atomic Write System Interacts with the Git Checkpoint Watcher

The AI-Memory wiki combines atomic file writes with immediate git checkpointing to guarantee durable, consistent storage: every page mutation is written atomically to disk, then committed to git, with a filesystem watcher triggering re-indexing only after the rename completes.

The akitaonrails/ai-memory repository implements a robust persistence layer where atomic write system and git checkpoint watcher work in tandem to ensure no data loss and consistent state across the filesystem, git history, and SQLite index. This article breaks down the exact interaction between these components as implemented in the Rust source code.

---

Atomic Write Pipeline in wiki.rs

All page mutations flow through a single pipeline in crates/ai-memory-wiki/src/wiki.rs. The atomic write system ensures readers never observe partially written files.

Content Assembly and Admission Hooks

Before any disk write, the page content (front-matter plus body) is assembled in memory. If an admission webhook chain is configured, it executes after markdown construction but before persistence【wiki.rs L99-L101】.

// Build the markdown content
let markdown = Markdown::new(frontmatter, body);

// Run admission webhooks (if any)
if let Some(chain) = self.admission_chain.as_ref() {
    let ctx = AdmissionContext::new(...);
    chain.run(&mut markdown, ctx).await?;
}

Temp-File-to-Rename Atomicity

The actual write uses crate::atomic::write_atomic, implemented in crates/ai-memory-wiki/src/atomic.rs. This helper:

1. Creates a temporary file in the same directory
2. Writes all bytes to the temp file
3. Renames it into the final destination

This pattern guarantees that any concurrent reader sees either the old complete file or the new complete file—never a partial write【wiki.rs L549-L551】.

// Atomic write – temp file → rename
crate::atomic::write_atomic(&abs_path, markdown.as_bytes())?;

---

Git Checkpoint Creation Immediately After Write

The git checkpoint watcher integration begins the moment the atomic write succeeds. The wiki calls GitAdapter::commit_all (via the commit_all helper) to capture the entire wiki tree state.

// Create a git checkpoint for the change
self.git.commit_all(&format!("write page {}", path.display()))?;

This creates a commit with a descriptive message like "write page path/to/file.md" in the hidden git repository at <data_dir>/wiki/.git. The checkpoint serves dual purposes: it provides durability through git's content-addressable storage, and it enables time-travel operations through the public API.

The Wiki::recent_checkpoints method exposes this history for CLI commands such as ai-memory checkpoints and restore-page【wiki.rs L228-L236】.

---

Filesystem Watcher Coordination

The final piece of the atomic write system and git checkpoint watcher interaction lives in crates/ai-memory-wiki/src/watcher.rs. This component must distinguish between transient temp files and committed page files.

Filtering Pending Paths

The watcher uses is_pending_path to ignore temporary files created during atomic writes. It reacts only to the final rename operation:

// In watcher.rs
if !is_pending_path(&event.path) {
    // The real page file just appeared/changed
    wiki.reindex_page(event.path).await?;
    // The GitAdapter already has a checkpoint for this change
}

Single-Transaction Re-indexing

Upon detecting a valid change, the watcher triggers re-indexing of the modified page. This updates the SQLite store in a single database transaction, maintaining synchronization between the filesystem and the search index. The git checkpoint already exists at this point—the watcher does not create it, only observes its result.

---

Component Interaction Flow

Understanding how these systems cooperate requires tracing a complete write operation:

1. Application layer calls wiki to save a page
2. Atomic write system assembles content, runs admission hooks, writes to temp file, renames into place
3. Git checkpoint is created immediately after successful rename
4. Watcher detects the rename (ignoring the temp file), re-indexes into SQLite
5. All three stores—filesystem, git repository, and SQLite—now reflect the same state

This sequence eliminates race conditions: the atomic write prevents torn reads, the git checkpoint captures state before any external process can modify files further, and the watcher-driven re-indexing ensures the search database stays consistent with the filesystem ground truth.

---

Key Source Files

File	Responsibility
crates/ai-memory-wiki/src/wiki.rs	Core wiki implementation, admission chain, atomic write orchestration, checkpoint creation【wiki.rs L99-L101】
crates/ai-memory-wiki/src/atomic.rs	Low-level write_atomic helper (temp file + rename)
crates/ai-memory-wiki/src/git.rs	GitAdapter wrapper around libgit2 for commit_all operations
crates/ai-memory-wiki/src/watcher.rs	Filesystem watcher with pending-file filtering and re-index triggers
docs/ARCHITECTURE.md	High-level documentation of wiki-git checkpoint relationships

---

Summary

• Atomic writes in ai-memory use temp-file-plus-rename semantics to guarantee readers never see partial content
• Git checkpoints are created synchronously after every successful atomic write, providing durable history
• The filesystem watcher ignores temporary files and triggers SQLite re-indexing only after the final rename completes
• These three mechanisms—atomic write system, git checkpoint creation, and watcher-driven re-indexing—maintain consistency across filesystem, git, and database stores
• CLI operations like restore-page leverage the checkpoint history exposed through Wiki::recent_checkpoints

---

Frequently Asked Questions

What happens if the atomic write succeeds but git checkpointing fails?

The page exists on disk with valid content, but no git history captures the change. The next successful operation will checkpoint the current state, though the specific mutation's provenance is lost. The system favors availability over strict atomicity across git boundaries.

How does the watcher distinguish temp files from real pages?

The is_pending_path function in watcher.rs checks path patterns. Atomic writes use predictable temporary naming conventions, allowing the watcher to filter these events and react only to the final rename that installs the completed file.

Can I disable git checkpointing while keeping atomic writes?

The current implementation couples these in wiki.rs—every successful write_atomic is followed by commit_all. To disable checkpoints, you would need to modify the wiki's save path to skip the git adapter call, though this isn't exposed as configuration.

What git operations occur during commit_all?

GitAdapter::commit_all stages all changes in the wiki directory and creates a commit with the provided message. It does not push to remotes—checkpoints remain local until explicit synchronization commands are invoked.

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