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

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 (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 (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, 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 (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 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, ensure existing knowledge bases upgrade safely without data loss.

According to 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:

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

# Read a specific page from wiki/

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

List and inspect the wiki structure:

# List all wiki pages in JSON format

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

Apply structural migrations when upgrading:

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

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, 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, 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 implementation expects specific file structures and Git states; manual modifications should follow the existing [[wikilinks]] conventions to prevent breaking query functionality.

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