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

> Discover how the AI-Memory wiki's atomic write system and Git checkpoint watcher ensure durable, consistent storage for every page mutation. Learn how re-indexing is triggered.

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

---

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

All page mutations flow through a single pipeline in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs#L99)】.

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs#L549)】.

```rust
// 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.

```rust
// 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](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs#L228)】.

---

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

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) | Core wiki implementation, admission chain, atomic write orchestration, checkpoint creation【[wiki.rs L99-L101](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs#L99)】 |
| [`crates/ai-memory-wiki/src/atomic.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/atomic.rs) | Low-level `write_atomic` helper (temp file + rename) |
| [`crates/ai-memory-wiki/src/git.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/git.rs) | GitAdapter wrapper around libgit2 for `commit_all` operations |
| [`crates/ai-memory-wiki/src/watcher.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/watcher.rs) | Filesystem watcher with pending-file filtering and re-index triggers |
| [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.