# How to Manually Edit ai‑memory Markdown Files and Reconcile Changes

> Learn to manually edit ai-memory Markdown files in the wiki tree. Reconcile changes automatically with the file watcher or force a reindex via CLI.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-06

---

**You can manually edit ai‑memory's Markdown files in the UUID‑based wiki tree and have them automatically reconciled by the file watcher, or force a full reindex using the CLI when the watcher is disabled.**

The `ai-memory` open-source project stores all knowledge as ordinary Markdown pages within a UUID‑based wiki tree. When you manually edit these files on disk, the system detects changes through an internal **watcher** process that automatically reconciles updates with the SQLite index and git history. For scenarios involving bulk edits or disabled watchers, the `ai-memory reindex` command provides a direct‑disk reconciliation pathway that rebuilds the entire search index from the current filesystem state.

## How Automatic Reconciliation Works

The reconciliation pipeline bridges filesystem changes with the internal database state through a sequence of atomic operations defined in [`crates/ai-memory-wiki/src/watcher.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/watcher.rs).

### The File System Watcher

The **watcher** runs continuously inside the server process, monitoring the UUID‑based wiki directory for create, modify, and delete events. When you save a Markdown file, the OS notifies the watcher, which invokes the `reconcile()` function at [watcher.rs:L163](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/watcher.rs#L163). This function reads the affected page, sanitizes the content, and updates the internal store via `reconcile(&wiki)` at [watcher.rs:L308](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/watcher.rs#L308).

### Internal Reconcile Pipeline

The reconciliation process executes four distinct phases atomically:

1. **Filesystem Event Detection** – The OS notifies the watcher of changes to the Markdown tree.
2. **Content Sanitization** – The `reconcile` function reads the page and validates front‑matter before writing via `Wiki::write_page` (using atomic tmp + rename patterns).
3. **SQLite Index Update** – The writer actor inserts or updates the `pages` row and rebuilds the relevant **FTS5** index entries.
4. **Git Checkpoint** – A lightweight git commit records the new state to [`docs/lifecycle-ops.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md), making the edit part of the permanent history without manual `git` commands.

## Reconciliation Methods

Depending on your editing context, choose between automatic reconciliation or a full manual reindex.

### Let the Watcher Run (Normal Editing)

For routine hand‑editing while the server is active, allow the watcher to handle synchronization automatically. This method is fastest and requires no CLI intervention. Simply edit any file under the wiki directory; the watcher receives the filesystem event and triggers `reconcile(&wiki)` to update the database and commit the checkpoint.

### Run a Full Reindex (Bulk Recovery)

When you have made many edits while the watcher was paused, or when you need to rebuild the index from scratch, use the CLI reindex command. According to the source code in [`docs/lifecycle-ops.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md) at lines 34‑36, the command `ai‑memory reindex --data-dir <data‑dir>` performs a direct‑disk operation that:

- Reads every Markdown file in the wiki tree
- Parses front‑matter and regenerates page metadata
- Rebuilds all link relationships and FTS entries
- Emits a final git checkpoint

**Critical Safety Note:** Because `reindex` operates directly on disk, you **must stop the server** before running it. The writer actor must not hold the SQLite WAL lock during the operation. Refer to the safety matrix in [`docs/lifecycle-ops.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md) for detailed lifecycle constraints.

## Step‑by‑Step Editing Workflows

### Editing a Single File

Open any page under the UUID‑based tree with your preferred editor. After saving, verify the automatic reconciliation:

```bash

# Edit a decision record

vim wiki/default/123e4567-89ab-cdef-0123-456789abcdef/decisions/0010.md

# Save and exit—the watcher automatically reconciles

# Confirm the content is searchable:

ai-memory search "new decision phrase"

```

### Bulk Editing and Reindexing

For mass updates made while the watcher was disabled, perform a full reindex:

```bash

# Stop the server to release the SQLite WAL

docker compose down

# Rebuild the index from current Markdown state

ai-memory reindex --data-dir /var/opt/ai-memory/data

# Restart the server

docker compose up -d

```

### Programmatic Reconciliation (Advanced)

You can trigger reconciliation programmatically using the internal Rust API from [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs):

```rust
use ai_memory_wiki::{Wiki, reconcile};

#[tokio::main]
async fn main() {
    let wiki = Wiki::open("/var/opt/ai-memory/data/wiki").await.unwrap();
    let stats = reconcile(&wiki).await.unwrap();
    println!("Reconciled {} pages", stats.pages_processed);
}

```

## Safety Requirements for Direct‑Disk Operations

Understanding when to stop the server prevents database corruption. The `reindex` command defined in [`crates/ai-memory-cli/src/commands/reindex.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/reindex.rs) requires exclusive filesystem access because it bypasses the writer actor's queue. In contrast, the automatic `reconcile` pass coordinates with the running server through message passing and requires no downtime. Always consult the **safety matrix** in [`docs/lifecycle-ops.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md) before performing direct‑disk operations.

## Summary

- **Automatic reconciliation** via the file watcher handles single‑file edits in real‑time using the `reconcile()` function in [`watcher.rs`](https://github.com/akitaonrails/ai-memory/blob/main/watcher.rs).
- **Full reindexing** via `ai‑memory reindex --data-dir` rebuilds the SQLite and FTS5 indexes from the entire Markdown tree, but requires stopping the server first.
- The **writer actor** manages atomic updates to the database and git history without manual SQL or git commands.
- All reconciliation paths preserve the **UUID‑based wiki structure** and maintain searchable, versioned knowledge.

## Frequently Asked Questions

### Does ai‑memory support manual editing of Markdown files?

Yes. The architecture specifically supports direct editing of Markdown files within the UUID‑based wiki tree. The **watcher** process detects filesystem changes and automatically reconciles them with the SQLite index, or you can run `ai‑memory reindex` to batch‑process manual changes.

### What is the difference between reconcile and reindex in ai‑memory?

**Reconcile** is an incremental, automatic process triggered by the file watcher for single changes, calling `reconcile(&wiki)` to update specific pages. **Reindex** is a complete rebuild of the search index from the filesystem, defined in [`crates/ai-memory-cli/src/commands/reindex.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/reindex.rs), which scans every Markdown file and regenerates the entire database state.

### Do I need to stop the server to edit Markdown files manually?

No for single edits—the running watcher handles reconciliation automatically. Yes for `reindex` operations—because the command performs direct‑disk reads and SQLite writes, the server must be stopped to prevent WAL conflicts with the writer actor.

### How does ai‑memory track changes to manual edits?

Every reconciliation pass creates a **git checkpoint** that commits the new Markdown state to the repository history. This happens automatically during the `reconcile` function execution or at the conclusion of a `reindex` operation, ensuring all manual edits remain versioned and recoverable.