# Structure of the LLM Wiki in ai-memory: Directory Layout, API, and Safety Guarantees

> Explore the LLM wiki structure in ai-memory. Discover its hierarchical directory layout, APIs for atomic writes, and robust safety guarantees for your data.

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

---

**The LLM wiki in ai-memory stores all markdown pages under a strictly hierarchical directory tree at `<data_dir>/wiki/<workspace_id>/<project_id>/`, enforced by the `Wiki` struct in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) and manipulated through path-building APIs that guarantee atomic writes and consistent SQLite indexing.**

The ai-memory repository implements a deterministic, namespaced storage layer called the **LLM wiki** that serves as the single source of truth for all markdown content indexed by the system. This Rust-based architecture organizes content by UUID-namespaced directories and provides crash-safe atomic writes through a well-defined public API. Understanding the wiki's structure is essential for developers integrating custom storage backends or extending the LLM-memory engine's document processing capabilities.

## Canonical Directory Layout and Namespace Hierarchy

All wiki pages reside under a root folder defined at runtime as `<data_dir>/wiki/`. Inside this root, the hierarchy follows a strict two-level UUID namespace that isolates workspaces and projects:

```text
<wiki_root>/
└── <workspace_id>/            # UUID of the workspace

    └── <project_id>/          # UUID of the project

        ├── <page-path>.md    # Regular wiki pages

        ├── sessions/
        │   └── <session_id>.md
        └── …                  # Any sub-folders you create

```

This layout is enforced as an invariant by the `Wiki` struct. According to the source code documentation at lines 71–84 of [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), developers must use the provided helper methods for path construction rather than hand-rolled path joins. This ensures that every file on disk matches the `(workspace_id, project_id, path)` triple stored in the SQLite metadata tables.

## Public API for Path Construction and Page Management

The `Wiki` struct exposes specific methods to compute canonical paths and persist content safely. These methods centralize the logic for translating logical page identifiers into absolute filesystem paths.

- **`Wiki::project_root(ws_id, proj_id)`** – Returns a `PathBuf` pointing to `<wiki_root>/<workspace_id>/<project_id>`. Implemented at lines 59–66 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs).
- **`Wiki::abs_path(ws_id, proj_id, page_path)`** – Returns the absolute `PathBuf` for a specific page file, resolving the full namespace hierarchy. Defined at lines 80–88 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs).
- **`Wiki::write_page(...)`** – Persists content atomically by internally invoking `abs_path` and updating the metadata store, guaranteeing that the SQLite index stays synchronized with the filesystem.

These helpers ensure that no page can be written outside its designated namespace and that all filesystem operations respect the internal locking mechanisms.

## Markdown Parsing and Link Extraction

Content processing lives in [`crates/ai-memory-wiki/src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/markdown.rs), which handles front-matter extraction, serialization, and link analysis.

The **`parse`** function (lines 34–47) recognizes YAML front-matter delimited by `---\n` and returns a `Markdown` struct containing `frontmatter` as a `serde_json::Value` and the raw body string. The corresponding **`emit`** function (lines 60–78) serializes the struct back to a string while preserving ordering and comments.

For relationship mapping, the **`extract_links`** function (lines 18–44) walk the markdown body while skipping fenced code blocks. It recognizes multiple link formats:

- Wiki-style links: `[[wiki links]]` and `[[workspace/project:path]]`
- Standard markdown: `[label](../path.md)`

The parser returns a vector of `LinkTarget` structs encoding the workspace, project, and path components. It automatically filters external URLs, anchors, images, and non-markdown assets, appending `.md` extensions when necessary and normalizing relative paths against the source page location.

## Safety Guarantees and Concurrency Controls

The wiki layer enforces three critical safety mechanisms to prevent data corruption during concurrent access or system crashes.

**Atomic Writes** – Every mutation passes through `atomic::write_atomic`, which guarantees crash-safety by writing to a temporary file and renaming it into place only after the content is fully persisted.

**Mutation Locking** – A `RwLock` named `mutation_lock` (initialized at lines 12–13 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs)) serializes writes that could clash with concurrent reads or file moves, ensuring readers never observe partial writes.

**Admission Chain** – Optional webhooks can inspect or reject changes before they touch the filesystem via `with_admission_chain` (lines 38–48). This preserves security and auditability by allowing external validation logic to intercept modifications.

## Summary

- The LLM wiki stores all content under `<data_dir>/wiki/<workspace_id>/<project_id>/`, using UUID namespaces to isolate workspaces and projects.
- Path construction is centralized in `Wiki::project_root` and `Wiki::abs_path` (lines 59–88 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs)) to enforce the directory invariant.
- The markdown parser in [`src/markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/src/markdown.rs) handles YAML front-matter and extracts internal wiki links via `extract_links` while ignoring code blocks and external URLs.
- All writes are atomic and protected by an `RwLock`, with an optional admission chain for webhook-based validation.

## Frequently Asked Questions

### Where are wiki pages physically stored on disk?

Pages are stored under the configurable data directory at `<data_dir>/wiki/<workspace_uuid>/<project_uuid>/<page-path>.md`. The `Wiki` struct enforces this layout through its internal path builders, ensuring that the filesystem hierarchy always matches the `(workspace_id, project_id, path)` metadata stored in SQLite.

### How does the wiki prevent data corruption during concurrent writes?

The implementation uses an `RwLock` (`mutation_lock` at lines 12–13 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs)) to serialize write operations, combined with `atomic::write_atomic` for crash-safe file persistence. This guarantees that readers never encounter partial files and that system crashes cannot leave the wiki in an inconsistent state.

### What link formats does the markdown parser recognize?

According to the `extract_links` implementation at lines 18–44 of [`markdown.rs`](https://github.com/akitaonrails/ai-memory/blob/main/markdown.rs), the parser recognizes wiki-style double-bracket links (`[[path]]` and `[[workspace/project:path]]`) as well as standard markdown links (`[text](../path.md)`). It automatically skips external URLs, image references, and code blocks.

### How does the admission chain integrate with page writes?

The `with_admission_chain` method (lines 38–48 of [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/wiki.rs)) allows the `Wiki` instance to register optional webhooks that inspect or reject mutations before they reach the filesystem. This enables external validation, audit logging, or policy enforcement while maintaining the atomic write guarantees of the underlying storage layer.