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

> Discover the source of truth in ai-memory storage architecture. Learn how the markdown wiki acts as the definitive source, while SQLite provides a rebuildable search index.

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

---

**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](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md#L21-L29)." 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](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md#L42)." 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](https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md#L92)." Similarly, the codebase memory MCP research specifies that "[markdown-in-git is the source of truth; SQLite `db/` is the index](https://github.com/akitaonrails/ai-memory/blob/main/docs/research-codebase-memory-mcp.md#L169)."

The README confirms this for end users, explaining that "[Your memory is plain markdown. The source of truth is a git-backed …](https://github.com/akitaonrails/ai-memory/blob/main/README.md#L43)." 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)](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)](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:

```bash
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:

```bash
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:

```bash
ai-memory reindex

```

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

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