wiki/, the compiler’s internal state lives in .llmwiki/, and every operation - ingest, compile, query - appends a timestamped entry to log.md. Wiki pages and the journal remain plain text you can open in Obsidian. The derived embedding index can use binary storage; other state files use JSON.
Output Directory Structure
The wiki/ Directory
wiki/concepts/
One Markdown file per compiled concept. Each file has YAML frontmatter with title, summary, kind, sources, timestamps, and optional epistemic metadata. The file body contains prose paragraphs with
^[source.md] citation markers and [[wikilinks]] to related concepts.wiki/queries/
Saved answers from
llmwiki query --save. Query pages are full wiki pages and participate in retrieval - future queries use them as context, compounding the wiki’s usefulness over time.wiki/index.md
An auto-generated table of contents rebuilt after every compile. Lists every concept page with its summary, grouped for navigation. Both the CLI and the local viewer use this as the primary entry point.
The .llmwiki/ Directory
state.json
Tracks per-source SHA-256 content hashes and the concept slugs each source owns. On every compile, llmwiki compares live file hashes against this state to determine what needs reprocessing. This is what makes incremental compilation possible.
Embedding index
The v3 embedding store carries page and chunk vectors under qualified page ids for query and context retrieval. Small stores use
embeddings.json; large or explicitly opted-in stores use embeddings.bin. Binary remains authoritative on later runs; an old JSON file is only a historical backup. See storage and recovery.candidates/
JSON records for pages held for review - either via
llmwiki compile --review, triggered automatically by a review policy in config.json, or staged by llmwiki import --okf. Each candidate records exactly why it was held (low confidence, contradicted, schema-violating, provenance-violating, or imported from OKF). Rejected candidates move to candidates/archive/ for audit.schema.json
An optional file you create with
llmwiki schema init. Defines which page kinds are permitted, per-kind minimum wikilink counts, and seed pages the compiler should materialize (such as domain-level overview pages). Projects without a schema file fall back to the concept kind for all pages.config.json
Holds the review policy: which hold modes are active (
low-confidence, contradicted, schema-violating, provenance-violating) and the lowConfidenceThreshold. A missing or empty config.json means all pages are written directly to wiki/ with no review step.Wikilinks and Alias Resolution
llmwiki uses standard[[double-bracket]] wikilink syntax throughout the wiki. During the interlink resolution phase, the compiler scans every concept page for title mentions and wraps them in [[slug|Title]] links. The piped alias form keeps Obsidian link resolution stable when a page’s filename differs from its display title. Mentions are linked only in prose: never in code, in a Markdown link’s text or URL, in image alt text, in a reference definition, or in a table cell, where the link’s | would split the cell.
You can also declare aliases in a page’s frontmatter to make a page reachable under multiple names:
[[multi-head self-attention]] or [[MHA]] link in the wiki resolves to this page, even if the slug is multi-head-attention. Alias resolution is honored by the local viewer, the MCP read_page tool, and llmwiki query.
The wiki is fully Obsidian-compatible. Open the
wiki/ directory as an Obsidian vault to browse compiled pages, follow wikilinks, and view the knowledge graph - no additional configuration required.Source Attribution
Every compiled page declares its source files in frontmatter:sources field lists the filenames from sources/ that contributed to this page. These filenames - combined with the content hashes recorded in .llmwiki/state.json - are what llmwiki compares on subsequent runs to determine whether a page is fresh, stale, or orphaned.
When multiple sources merge into one page, all contributing source filenames appear in the sources array.
Imported OKF Provenance
Pages imported from Open Knowledge Format bundles are marked as imported knowledge. The mapped page frontmatter carriesprovenanceState: imported, an okf:<bundle> source token, and an x-okf provenance snapshot that records the original bundle path and original OKF frontmatter.
This imported provenance is used for honest re-export: llmwiki export --target okf preserves foreign producer keys and raw foreign type values, restores safe original bundle paths, and derives standard OKF fields from the current llmwiki page so local edits are reflected.
OKF import is review-gated by default. External bundle content is staged as review candidates and does not become live wiki content until you approve it. Use
llmwiki import --okf <dir> --trusted only for bundles you already trust.The Activity Journal (log.md)
Every ingest, compile, and query operation appends a timestamped entry to log.md at the project root. Entries use a fixed heading format - ## [YYYY-MM-DDThh:mm:ssZ] operation | description - followed by a short bullet body carrying page wikilinks and counts:
## [, you can reliably extract recent operations with standard shell tools:
log.md tracks temporal progression - when things were compiled and in what order. wiki/index.md organizes content for discovery. Both are human-readable and machine-parseable.