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

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

<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, 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.
• 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.
• 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, 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) 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) to enforce the directory invariant.
• The markdown parser in 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) 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, 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) 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.

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