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

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.

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. This function reads the affected page, sanitizes the content, and updates the internal store via reconcile(&wiki) at 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, 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 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 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:

# 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:

# 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:

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 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 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.
• 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, 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.

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