Skip to content

OKF Compatibility

Jump to bottom
Chris Sweet edited this page Jul 14, 2026 · 1 revision

type: reference up: "Knowledge-Bundles-Overview" related:

OKF Compatibility

How llm-wiki knowledge bundles relate to Google's Open Knowledge Format (OKF) v0.1. Grounded in the OKF v0.1 spec and the template's own empirical analysis (the template wiki's OKF-Alignment-Ideas page, which read the spec and tested link rendering on a live GitHub wiki).

Status summary (as of 2026-07-14): bundles are format-conformant with OKF at the frontmatter level and diverge at two layers (reserved filenames, cross-link syntax). OKF import and OKF export are designed but not implemented in the template today. Consuming an OKF bundle by query (ask) is possible; absorbing one (import) is not yet.

Is the KB OKF compatible?

Partly, and deliberately so. A bundle is frontmatter-conformant with OKF v0.1: it is a directory of Markdown files with YAML frontmatter, type: is required on every page, and the conformance model is the same permissive one OKF specifies in §9 (tolerate unknown types, unknown keys, and broken links). A strict OKF consumer reading a bundle sees valid OKF concept files, and our typed edges (extends:, supports:, etc.) sit safely inside OKF's preserve-unknown-keys envelope (§4.1).

Two known deviations keep it from being byte-for-byte OKF:

  1. Reserved filenames. OKF reserves index.md and log.md (§6, §7). Bundles namespace them (index_<repo>.md, log_<repo>.md) so multiple bundles aggregate into one Obsidian vault without collisions. A strict OKF consumer would read these as ordinary concept files, not as the OKF index/log.
  2. Cross-link syntax. OKF recommends absolute bundle-relative links ([x](/tables/x.md)) or relative (./x.md). The template empirically tested these on the live GitHub wiki: the .md suffix routes clicks to the raw-markdown CDN and a leading slash 404s. So OKF's link form is inherently incompatible with GitHub-wiki rendering, and bundles use bare-slug body links ([Display](Page-Name)) plus [[Page-Name]] wikilinks in frontmatter instead.

So the honest statement: OKF-shaped and frontmatter-conformant, not byte-for-byte OKF at the filename and link layers. Full conformance for exchange is the job of a planned export (see below). See Wiki-Structure-and-Conventions for the link and frontmatter conventions.

What are the differences between llm-wiki KBs and OKF?

They share a lineage (OKF cites the Karpathy/tobi llm-wiki pattern as prior art), so the core is the same: Markdown + YAML frontmatter + Markdown cross-links + an index and a log + producer/consumer separation + git-shippable + permissive conformance. The differences:

Dimension OKF v0.1 llm-wiki KB
Folder structure nested directories, per-directory index.md flat GitHub wiki
Reserved filenames index.md, log.md index_<repo>.md, log_<repo>.md (Obsidian-vault namespacing)
Cross-link syntax /path/file.md absolute or ./x.md [Display](Page-Name) body, [[Page-Name]] frontmatter (GitHub-wiki-forced)
Edge semantics untyped (relationship in prose, §5.3) typed (extends/supports/criticizes/…), a superset
Storage substrate any directory / tarball / git repo GitHub wiki sub-repo (also git)
Beyond the format format only discipline layer: verification gate, typed-edge KG, multi-writer write protocol, federation (ask)

The one-line framing (from the template's Knowledge-Bundles-Framing): OKF is the wire format; the KB adds the discipline layer. OKF is minimally opinionated on purpose; the KB is a more-opinionated, typed superset that trades some raw-OKF portability for queryable structure and authoring discipline. See Concepts-Glossary for OKF, RDF, and typed-edge definitions.

Can I import my OKF bundle?

Not with a shipped command today (as of 2026-07-14). OKF import is a designed path, not an implemented one: it is Vector 4 of the template wiki's OKF-Alignment-Ideas analysis (adopt.sh --seed-from-okf=<bundle>), and adopt.sh itself was still in progress upstream. When it lands, it is expected to: validate the bundle is OKF-conformant (§9), copy the tree into wiki/<repo>.wiki/ after init-wiki.sh, rewrite [x](/path.md) links to [[wikilinks]], optionally infer typed edges (opt-in because it is lossy), and emit a corrections-log entry recording the import policy. Until then, importing an OKF bundle is a manual operation: clone it, rename index.md/log.md to the namespaced form, and rewrite the body links.

Important distinction: you cannot yet import (absorb-and-evolve), but you can already query an OKF bundle without owning it. The agent-comms ask primitive runs an LLM over any cloneable directory of Markdown-plus-frontmatter, and an OKF bundle is exactly that (Vector 5 of OKF-Alignment-Ideas). Given a federation entry or a direct clone, ask works against an OKF bundle today. So: query now, import later. See Extending-the-Template and Knowledge-Bundles-Overview.

Can I export my KB to OKF?

Not with a shipped command today (as of 2026-07-14). An OKF export (scripts/export-okf.sh) is explicitly deferred in the template's OKF-Alignment-Ideas ("only if external bundle exchange becomes a real ask"). When built, it would walk the wiki, rewrite bare-slug and [[wikilink]] body links to OKF's /path.md form, emit canonical index.md and log.md, and produce an OKF-conformant bundle directory an OKF tool (Google's static visualizer, Knowledge Catalog, or another consumer) could read.

What you can do today:

  • The frontmatter is already largely OKF-conformant, so a consumer that only reads frontmatter needs little translation.
  • The knowledge-graph pipeline emits RDF (JSON-LD and Turtle) via ./scripts/kg/build-graph.sh (see Knowledge-Graph). That is a standards-based interop surface, but it is RDF, not OKF; the two are different targets.
  • A manual export is possible by transforming links and filenames by hand.

If real OKF exchange becomes a need, the export script is the intended path, and adopting OKF's optional resource: frontmatter field (see Bundle-Pages-and-Supplementary-Data) is a cheap step toward it.

See also

Clone this wiki locally