Architecture of an LLM Wiki¶

The architecture of an LLM Wiki is fundamentally different from a standard Retrieval-Augmented Generation (RAG) pipeline. While RAG operates as a stateless lookup mechanism attached to a generic LLM, the LLM Wiki pattern establishes a stateful, hierarchical system where the LLM acts as an active maintainer of an intermediate knowledge graph.

This document breaks down the structural components, data flows, and performance considerations of the LLM Wiki architecture.

Component Breakdown¶

The architecture is built upon three primary layers:

1. The Raw Sources Layer¶

This is the foundational layer. It consists of immutable, curated documents. - Raw Files (raw/): A directory containing the actual source material. This includes PDFs, raw markdown clippings (for example, from Obsidian Web Clipper), meeting transcripts, and raw data files. - Media Assets (raw/assets/): Downloaded images, charts, and media referenced by the raw files. Keeping these local makes sure that external URLs do not break and allows vision-capable LLMs to process them securely. - Immutability Contract: The LLM is granted read-only access to this layer. It can never modify, summarize over, or delete a raw source. This makes sure that the ground truth is always preserved.

2. The Wiki Layer¶

This is the "compiled" persistence layer owned by the LLM. It acts as the synthesized interface between the raw data and the user. - Topic Hubs (index.md files): Directory-level landing pages that summarize a specific domain, link to child pages, and outline outstanding questions. - Entity & Concept Pages: Dedicated markdown files representing specific people, products, architectural patterns, or ideas (for example, kubernetes.md or andrej-karpathy.md). - Global Index (index.md / wiki-index.md): The master catalog of the entire wiki. It lists every page, a one-line summary, and metadata (like source count). - Audit Log (log.md): A chronological, append-only record of every action the LLM took (ingests, queries, lint passes). This allows system rollback and state tracking.

3. The Schema / Control Plane¶

This layer dictates how the LLM interacts with the Wiki layer. - Instruction Schema (CLAUDE.md, AGENTS.md): The configuration file containing the rules of engagement. It defines the folder shapes, required markdown conventions (for example, MkDocs admonitions), linking rules, and anti-hallucination guardrails. - Agent Runtime (Claude Code / Codex): The execution engine that processes tasks according to the schema. - Local Search Engine (qmd): An optional but critical component for scaling. It provides BM25 and vector search capabilities to the Agent Runtime via the Model Context Protocol (MCP). This bypasses context window limitations.

How It Works: The Ingestion Lifecycle¶

The defining feature of the LLM Wiki is the ingestion process—the act of "compiling" raw sources into the knowledge graph.

Ingestion Data Flow¶

When a new file is dropped into the Raw Sources layer, the LLM initiates the ingestion workflow:

sequenceDiagram
    participant User
    participant Agent as LLM Agent (Claude Code)
    participant Raw as Raw Sources Layer
    participant Wiki as Wiki Layer
    participant Search as Search Engine (qmd)

    User->>Raw: Adds `new-article.md`
    User->>Agent: "Ingest this source"
    Agent->>Raw: Reads `new-article.md`
    Agent->>Search: Queries existing concepts related to article
    Search-->>Agent: Returns relevant `entity.md` paths

    rect rgb(30, 40, 50)
        Note over Agent,Wiki: The Synthesis Phase
        Agent->>Wiki: Creates `ref-new-article.md` (Provenance)
        Agent->>Wiki: Updates `entity.md` (Integrates new facts)
        Agent->>Wiki: Flags contradictions in `entity.md` (if any)
    end

    Agent->>Wiki: Updates Global `index.md`
    Agent->>Wiki: Appends entry to `log.md`
    Agent-->>User: "Ingestion complete. Updated 3 pages."

1. Source Reading and Fact Extraction¶

The LLM parses the raw markdown. If images are present, it invokes vision capabilities to extract diagrams or charts. It identifies key entities, claims, and architectural patterns.

2. Context Retrieval¶

Before writing, the LLM reads the Global index.md (or uses qmd) to determine if pages already exist for the identified entities.

3. Incremental Synthesis¶

This is the core "compilation" step. The LLM does not just copy the source. It actively merges the new facts into existing pages. - If the new source states that a tool has a new feature, the LLM appends it to the architecture.md of that tool. - If the new source contradicts an existing claim, the LLM explicitly documents the contradiction (for example, with a > [!WARNING] admonition).

4. Bookkeeping¶

The LLM makes sure that the graph remains navigable. It adds bidirectional wikilinks, updates the YAML frontmatter (for example, last_checked: 2026-07-01), and writes a timestamped summary of its actions to log.md.

System Architecture: RAG vs. LLM Wiki¶

To fully understand the LLM Wiki, it must be contrasted with standard stateless RAG.

flowchart TD
    subgraph "Stateless RAG Pattern"
        R1[Raw Document] --> R2[(Vector DB)]
        R3[User Query] --> R4[Similarity Search]
        R2 -.-> R4
        R4 --> R5[LLM Context Window]
        R5 --> R6[Ephemeral Answer]
    end

    subgraph "LLM Wiki Pattern (Stateful)"
        W1[Raw Document] --> W2[LLM Agent]
        W2 -- Ingests & Synthesizes --> W3[(Markdown Wiki)]
        W3 -- Cross-References --> W3
        W4[User Query] --> W5[LLM Agent]
        W5 -- Reads Compiled Wiki --> W3
        W3 -.-> W5
        W5 --> W6[Answer / New Wiki Page]
        W6 -- Files Back --> W3
    end

In the stateless pattern, the LLM must do heavy reasoning and synthesis at query time. It deals with fragmented, conflicting chunks retrieved by a dumb vector search. In the LLM Wiki pattern, the LLM does the reasoning and synthesis at ingest time. The vector search (if used) retrieves highly structured, pre-synthesized markdown. This drastically reduces query latency and hallucinations.

Scalability and Benchmarks¶

The primary constraint on an LLM Wiki is not the size of the raw data, but the ability of the LLM to navigate the compiled markdown structure.

1. Small Scale (0 - 100 Sources, ~200 Pages)¶

At this scale, the architecture relies purely on the Global index.md and log.md. - Mechanism: The LLM reads the index (which contains a 1-line summary of every page), decides which 3-5 pages are relevant to the query, and reads them directly. - Performance: Highly efficient. Token usage is minimal because the index file remains small (approx. 5,000 - 10,000 tokens). Query latency is dominated by file read I/O, which is negligible on local SSDs.

2. Medium Scale (100 - 1,000 Sources, ~2,000 Pages)¶

The global index becomes too large for efficient context-window usage. - Mechanism: Introduction of hierarchical indices. The domain landing pages (for example, knowledge/databases/index.md) act as routing nodes. The LLM reads the root index, jumps to the domain index, and then to the specific page. - Performance: Slower due to sequential tool calls (read root -> read domain -> read page). Token usage increases slightly.

3. Large Scale (1,000+ Sources, 5,000+ Pages)¶

Hierarchical traversal becomes brittle and slow. The architecture requires a dedicated retrieval engine. - Mechanism: Integration of tools like qmd (Query Markup Documents). The LLM drops manual traversal and issues MCP queries to qmd. - qmd Internals: qmd uses a hybrid BM25 (keyword) and Vector (semantic) pipeline with LLM re-ranking, processed entirely on-device via node-llama-cpp and GGUF models — no cloud API calls. It ships both a CLI (so the agent can shell out to it) and an MCP server (so the agent can call it as a native tool). Install: npm install -g @tobilu/qmd. - Performance: Query time stabilizes. The LLM only processes the highly relevant files returned by qmd. The local reranker makes sure that context windows are not flooded with tangential data. - Practical threshold: community reports place the breaking point of the single-index pattern at roughly 100-150 articles — well before the theoretical context-window limit — because index summaries lose discriminative power long before they stop fitting in context.

Failure Modes & Maintenance¶

A compiled wiki degrades without periodic maintenance passes, exactly like a codebase without linting:

Index drift: pages exist on disk but are missing from the global index (or vice versa). Mitigation: a scheduled lint task that diffs the file tree against the index.
Orphan pages: entity pages with no inbound links become unreachable through navigation and only surface via search. Mitigation: backlink audits during ingestion.
Duplicate entities: the same concept accumulates two pages under different names (for example, k8s.md and kubernetes.md). Mitigation: search-before-create rules in the schema file.
Stale synthesis: an entity page contradicts newer raw sources that were never ingested against it. Mitigation: last_checked frontmatter and periodic re-verification sweeps.
Log bloat: the append-only log.md grows unbounded. Mitigation: roll logs by month and keep only recent history in the default reading path of the agent.

Community implementations confirm the pattern runs fully offline — for example, NiharShrotri's llm-wiki pairs Ollama-served Qwen3 with qmd for both synthesis and retrieval. This demonstrates that no frontier cloud model is strictly required for the maintenance loop.

Git as the State Store¶

Most implementations layer the wiki on a git repository, which supplies three architectural properties the filesystem alone lacks:

Atomic snapshots: a commit per ingestion run groups all page mutations from one source. This makes partial-ingest corruption detectable and revertible as a unit.
Distributed durability: a private remote mirror doubles as backup without introducing a database dependency.
Diff-based review: humans review agent changes as diffs (or pull requests in team deployments) rather than re-reading whole pages, which is what makes the human-in-the-loop checkpoint practical at scale.

Security¶

The LLM Wiki pattern fundamentally alters the security and privacy model of AI-assisted knowledge management. By shifting from cloud-based RAG platforms to a local-first, agent-driven workflow, you regain data sovereignty while introducing new risks related to agent filesystem access.

This document outlines the threat model, access controls, and encryption strategies necessary to secure an LLM Wiki.

1. Identity & Authentication (Auth)¶

In a traditional cloud RAG system (for example, ChatGPT or NotebookLM), authentication is handled by the vendor. In a local LLM Wiki, authentication is decoupled into two distinct domains: Human Auth and Agent Auth.

Human Authentication¶

Because the wiki is stored as a directory of markdown files (often inside Obsidian), human access is governed by the host operating system. - Local Access: Authentication relies on standard OS-level login mechanisms (biometrics, passwords). - Remote Access: If the wiki is synced across devices (for example, via Obsidian Sync or Git), authentication is handled by the sync provider. Obsidian Sync uses E2EE with a custom password, while Git relies on SSH keys or Personal Access Tokens (PATs).

Agent Authentication¶

The AI agent (Claude Code, Codex, or local models) must be authenticated to interact with your data. - API Keys: For cloud-backed agents (like Claude Code), API keys must be secured in local environment variables (for example, .zshrc or .env files) and never committed to the wiki repository. - Model Context Protocol (MCP): If the agent uses qmd or other MCP servers to read the wiki, the MCP server runs locally under the user's OS permissions. No separate authentication is required between the agent CLI and the local MCP server, provided both run on the same machine under the same user profile.

2. Access Control (Authz)¶

Authorization is the primary security challenge when using autonomous agents. Giving an LLM agent read/write access to your local filesystem carries inherent risks.

Agent Permissions Model¶

Scoped Read/Write: Restrict agents to the specific directory containing the knowledge base (for example, ~/Documents/obsidian-vault/). Never run them from the root directory (/) or the ~ home directory. There they can read SSH keys or system configurations.
The Raw Sources Immutability Contract: As defined in the architecture, the raw/ directory must be treated as read-only by the agent. While local operating systems do not easily enforce granular read-only permissions for specific scripts running under the user profile, this constraint must be heavily enforced via the system prompt of the agent (for example, inside AGENTS.md).

Multi-User / Internal Team Wikis¶

If the LLM Wiki pattern is deployed for a business or team, authorization becomes more complex: - Role-Based Access Control (RBAC): In a team setting, the wiki is typically hosted in a central Git repository. The agent runs in a CI/CD pipeline. It processes PRs or new documents. Human engineers review the markdown that the agent generates before merging. - Segregation of Duty: The agent has write access to the feature branch, but only human maintainers have merge permissions to main.

3. Threat Model & Encryption¶

Data Leakage via Prompts¶

When using cloud-backed agents (for example, Anthropic API, OpenAI API), the contents of your local markdown files are transmitted to the cloud provider during ingestion and query phases. - Risk: Sensitive personal data, trade secrets, or proprietary code within the wiki can be logged by the API provider. - Mitigation: Rely on enterprise API agreements that guarantee zero-data retention (data is not used for model training). For absolute security, replace the cloud agent with a local GGUF model running on llama.cpp or Ollama.

Malicious Prompt Injection via Raw Sources¶

Risk: A user ingests a malicious webpage or PDF containing prompt injection attacks (for example, hidden text instructing the agent to delete the workspace).
Mitigation: Modern agents (like Claude Code) employ tool-use confirmation and sandboxing. This requires user approval for destructive commands (like rm). The agent must never have permission to execute code found within a raw source without explicit human consent.

Data at Rest Encryption¶

Because the wiki is stored as plain-text markdown, it is highly vulnerable to physical theft or unauthorized local access. - Full Disk Encryption (FDE): Make sure that FileVault (macOS), BitLocker (Windows), or LUKS (Linux) is enabled on the host machine. - Vault-Level Encryption: For highly sensitive wikis, use tools like Cryptomator to create an encrypted virtual drive where the markdown files are stored. The LLM agent can only access the files when the drive is mounted and decrypted by the user. - Sync Encryption: If you use cloud sync (Git, iCloud, Dropbox), make sure that End-to-End Encryption (E2EE) is applied before the data leaves the local machine.

Supply Chain Considerations¶

The local-first toolchain still has a supply chain that must be trusted:

qmd and its runtime: qmd is distributed via npm (@tobilu/qmd) and executes local GGUF models through node-llama-cpp. Pin the package version, review its dependency tree on upgrades, and download GGUF models only from verified publishers on Hugging Face (checksum-verified) — a poisoned reranker model silently shapes what the agent reads.
Agent CLI updates: Claude Code, Codex, and similar CLIs auto-update by default in many setups. In a high-sensitivity wiki, pin agent versions and review changelogs before upgrading, because the agent holds read/write access to the entire knowledge base.
MCP servers: every MCP server added to the agent is code running with your user's OS permissions. Prefer first-party or audited servers. Treat unknown MCP servers as untrusted code.

Versioning as a Security Control¶

Running the wiki as a git repository is not just a sync mechanism — it is the rollback and audit layer:

Every agent mutation is diffable and revertible (git diff, git revert), which converts "the agent corrupted my notes" from a disaster into an inconvenience.
Commit-level attribution separates human edits from agent edits when commits are made per-session.
A remote (private) mirror protects against local destruction. This complements the append-only log.md.

For the provider-side retention questions raised by cloud-backed agents, see the sibling topic Zero Data Retention, which covers ZDR contracts, Covered-Model carve-outs, and PII redaction proxies in depth.

Summary Checklist¶

Make sure that API keys are stored securely in environment variables, not in the wiki.
Run the agent ONLY within the scoped knowledge directory.
Enforce the "Read-Only Raw Sources" rule in the AGENTS.md schema.
Enable Full Disk Encryption on the host machine.
Make sure that the agent requires human approval for terminal commands.
Pin qmd/agent versions and verify GGUF model checksums.
Keep the wiki under git with a private remote for rollback and audit.