# Understanding the wiki/ Directory in ai-memory: Core Architecture and Usage

> Discover the purpose of the wiki/ directory in ai-memory. Learn how this Git-versioned knowledge base stores Markdown pages for long-term memory persistence, distinct from SQLite logs.

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

---

**The `wiki/` directory in ai-memory serves as a Git-versioned, plain-text knowledge base that stores compiled Markdown pages, acting as the primary persistence layer for long-term memory separate from raw SQLite logs.**

The `akitaonrails/ai-memory` project implements a unique approach to AI memory management by centralizing durable knowledge in a dedicated `wiki/` directory within the data folder. Unlike transient session logs, this directory maintains human-readable, inter-linked Markdown files that function as the system's source of truth for all retrieval, summarization, and reasoning operations.

## What is the wiki/ Directory?

At its core, the `wiki/` directory (default location: `<data_dir>/wiki`) contains the compiled output of the LLM's extraction process. When the system ingests information, it does not merely append raw observations to a database. Instead, as implemented in the repository's architecture, the LLM processes key facts into structured Markdown pages with [[wikilinks]] and writes them to this dedicated folder.

According to [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) (line 498), this approach ensures that every piece of long-term knowledge lives as plain Markdown plus Git history rather than opaque binary storage. The separation guarantees that AI-generated content never contaminates the user's actual project repository, residing completely outside the user's code workspace.

## Architectural Characteristics of the wiki/ Directory

### Compiled Knowledge, Not Raw Logs

The fundamental distinction of the `ai-memory` system lies in its transformation pipeline. Raw session data undergoes LLM-driven extraction to produce inter-linked Markdown pages. This compiled knowledge resides in `wiki/` rather than transient SQLite rows, enabling semantic relationships through wiki-style linking and creating a browsable knowledge graph.

### Git-Versioned Persistence

Every change within the `wiki/` directory is tracked as a Git commit, creating an auditable history of the AI's evolving understanding. As documented in [`docs/wiki-migrations.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/wiki-migrations.md) (line 9), this versioning applies not only to content but also to structural changes, allowing the system to migrate page layouts safely across versions while maintaining human-readable diffs.

### Isolation from Project Code

The wiki directory operates as a regular Git repository completely outside the user's project repository. This architectural boundary, emphasized throughout [`docs/architecture.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/architecture.md), ensures that memory operations—writes, updates, and deletions—occur within the AI's dedicated storage space without touching the user's source files.

## How Query Tools Interact with the wiki/ Directory

All memory-query operations read from the compiled wiki pages rather than raw database rows. Tools such as `memory_query`, `memory_lint`, and `memory_status` parse the Markdown files in `wiki/` to retrieve context, validate links, and report status.

As noted in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) (line 376), the wiki serves as the primary source of truth for:

- **Retrieval**: Fetching relevant context through page content and links
- **Summarization**: Aggregating information across multiple linked pages  
- **Auto-improvement**: Enabling LLM-driven refactoring of its own knowledge base

The implementation in [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) provides the low-level API for these atomic read/write operations, handling filesystem interactions and exposing them through the MCP server interface.

## Managing wiki/ Structure and Migrations

When the on-disk layout evolves—for example, transitioning from `<wiki_root>/<page>.md` to `<wiki_root>/<workspace>/<project>/<page>.md`—the system applies **wiki migrations**. These transformations, registered in [`crates/ai-memory-wiki/src/migrations/mod.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/migrations/mod.rs), ensure existing knowledge bases upgrade safely without data loss.

According to [`docs/wiki-migrations.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/wiki-migrations.md) (line 13), migrations trigger when:

- Directory path schemes change
- Page naming conventions require updates  
- Structural relationships between concepts shift

## Practical Operations with the wiki/ Directory

Interact with the wiki layer through the CLI to persist and retrieve knowledge:

```bash

# Write a durable page to the wiki/ directory

ai-memory memory_write_page \
  --path concepts/ai-memory \
  --title "AI-Memory Architecture" \
  --body "$(cat <<'EOF'

# AI-Memory Architecture

ai-memory is built around a Git-backed markdown wiki.
- Pages are plain Markdown.
- Links are created with [[wikilinks]].
- Each page is versioned via Git.
EOF
)"

```

Retrieve existing knowledge with:

```bash

# Read a specific page from wiki/

ai-memory memory_read_page --path concepts/ai-memory

```

List and inspect the wiki structure:

```bash

# List all wiki pages in JSON format

ai-memory memory_list_pages --format json | jq '.pages[] .path'

```

Apply structural migrations when upgrading:

```bash

# Run a migration that renames the old _logs folder to _log

ai-memory wiki_migrate m2026_06_01_1200_rename_logs_dir

```

These commands demonstrate the standard workflow for **writing**, **reading**, **listing**, and **migrating** content inside the `wiki/` directory.

## Summary

- The `wiki/` directory stores **compiled Markdown knowledge** extracted by the LLM, not raw session logs.
- It functions as a **Git-versioned repository**, providing human-readable, auditable history at `<data_dir>/wiki`.
- All query tools (`memory_query`, `memory_lint`, `memory_status`) read from `wiki/` as the **primary source of truth**.
- The directory resides **outside the user's project code**, ensuring isolation between AI memory and source files.
- **Wiki migrations** handle structural evolution safely, registered in [`crates/ai-memory-wiki/src/migrations/mod.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/migrations/mod.rs).

## Frequently Asked Questions

### How does the wiki/ directory differ from the SQLite database in ai-memory?

The SQLite database contains transient, raw session data and operational metadata, while the `wiki/` directory holds the **compiled, long-term knowledge** in Markdown format. Query tools read exclusively from the wiki pages, not the raw database rows, ensuring retrieval operates on processed, inter-linked information rather than unprocessed logs.

### Can I browse the wiki/ directory with a standard file browser or IDE?

Yes. Because the wiki consists of plain Markdown files with standard [[wikilinks]], you can open `<data_dir>/wiki` in any text editor, Obsidian, or VS Code. As documented in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md), the Git history is also fully accessible through standard Git tooling, making the knowledge base completely portable and inspectable without specialized tools.

### What triggers a wiki migration in ai-memory?

A wiki migration executes when the on-disk layout changes, such as moving from a flat structure (`<wiki_root>/<page>.md`) to a nested workspace structure (`<wiki_root>/<workspace>/<project>/<page>.md`). According to [`docs/wiki-migrations.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/wiki-migrations.md), these migrations safely transform existing files to match new path schemes when the path scheme changes, without manual intervention.

### Is the wiki/ directory safe to delete or manually edit?

While manual edits are possible since the files are plain Markdown, deleting the directory destroys the system's long-term memory. The [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) implementation expects specific file structures and Git states; manual modifications should follow the existing [[wikilinks]] conventions to prevent breaking query functionality.