What Is the Source of Truth in the ai-memory Storage Architecture?

The markdown wiki is the source of truth in ai-memory, while the SQLite database serves only as a rebuildable search index.

The akitaonrails/ai-memory project implements a storage architecture that prioritizes data durability and version control by designating plain-text markdown files as the authoritative record. Unlike traditional applications where a database holds primary state, ai-memory inverts this model—the filesystem containing your markdown wiki is the permanent source of truth in the ai-memory storage architecture, and the SQLite layer exists solely to accelerate queries.

Understanding the Storage Architecture

The Markdown Wiki as Source of Truth

According to the architecture documentation, the system explicitly treats "the markdown wiki is the source of truth, and SQLite is the derived search/index layer." This design choice means that every piece of content lives as a .md file within the wiki directory, tracked by git, and human-readable without specialized tooling.

The design decisions document reinforces this by stating the project selected "Option B – markdown in a git repo is source of truth, SQLite is derived index." This approach ensures that even if the database is corrupted or deleted, the entire knowledge base can be reconstructed from the filesystem alone.

The SQLite Database as Derived Index

The SQLite database located in <data_dir>/db/ is never the authoritative copy. As noted in the basic-memory research documentation, the architecture follows the principle that "Files are source of truth, DB is derived index." Similarly, the codebase memory MCP research specifies that "markdown-in-git is the source of truth; SQLite db/ is the index."

The README confirms this for end users, explaining that "Your memory is plain markdown. The source of truth is a git-backed …." The database merely caches vector embeddings and full-text search indices to enable fast retrieval, but it is treated as ephemeral and rebuildable via the reindex operation.

How the Architecture Enforces the Source of Truth

The implementation enforces this hierarchy through specific modules. In [crates/ai-memory-wiki/src/wiki.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), the core wiki implementation handles atomic writes directly to markdown files, ensuring the filesystem remains the primary recipient of all mutations. The [crates/ai-memory-store/src/reader.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) module then accesses these files directly when serving content, rather than treating the SQLite store as the primary interface.

When you interact with ai-memory, all write operations target the markdown source. For example, creating a new page via the CLI writes directly to the filesystem:

ai-memory write-page my-note.md \
  --title "My Note" \
  --body "This is the authoritative content stored in the markdown wiki."

Reading content via the HTTP API ultimately resolves to the markdown source as well:

curl http://localhost:49374/api/v1/pages/my-note.md

If you manually edit markdown files outside the application, you must synchronize the derived index:

ai-memory reindex

Programmatically, the Rust Reader struct provides access to the source files:

use ai_memory_store::Reader;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let reader = Reader::new().await?;
    let page = reader.get_page("my-note.md").await?;
    println!("Title: {}", page.title);
    println!("Body:\n{}", page.body);
    Ok(())
}

Key Files Defining the Source of Truth Pattern

Several source files codify this architectural decision:

• [docs/ARCHITECTURE.md](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) — Defines the high-level separation between markdown source and SQLite index.
• [crates/ai-memory-wiki/src/wiki.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) — Implements atomic writes to markdown files, enforcing the filesystem as source of truth.
• [crates/ai-memory-store/src/reader.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) — Reads pages from markdown source rather than relying solely on the database cache.
• [docs/design-decisions.md](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) — Documents the intentional architectural choice to use markdown-in-git as the single source of truth.
• [README.md](https://github.com/akitaonrails/ai-memory/blob/main/README.md) — User-facing documentation confirming the git-backed markdown wiki is the authoritative storage.

Summary

• The markdown wiki is the immutable source of truth in ai-memory, stored as plain-text files under version control.
• The SQLite database is a derived, rebuildable index that enables fast vector search and full-text retrieval but holds no authoritative state.
• All write operations target the filesystem first, with the database updated asynchronously to reflect changes.
• Key enforcement happens in crates/ai-memory-wiki/src/wiki.rs and crates/ai-memory-store/src/reader.rs, which prioritize markdown files over database records.

Frequently Asked Questions

What happens if the SQLite database is deleted?

If the SQLite database is deleted or corrupted, ai-memory can reconstruct the entire search index from the markdown source files using the reindex command. Since the markdown wiki in the git repository remains intact, no data is lost.

Can I edit markdown files directly without using the CLI?

Yes. Because the filesystem is the source of truth, you can edit .md files directly with any text editor. After manual modifications, run ai-memory reindex to synchronize the SQLite search layer with your changes.

Why does ai-memory use SQLite if it's not the source of truth?

SQLite serves as a high-performance derived index that caches vector embeddings and full-text search indices. This design allows complex semantic queries to execute quickly while maintaining the durability and portability of plain-text markdown files as the permanent record.

How does the application prevent write conflicts between the database and markdown files?

The application treats the markdown filesystem as the primary write target. The ai-memory-wiki crate handles atomic writes to markdown files, and the store layer reads from these files directly, ensuring the database never diverges from the authoritative source.

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