theheavenlyd3mon Open Knowledge Format (OKF) — v0.1
Google Cloud published the Open Knowledge Format v0.1 on June 12, 2026 — an open specification that formalizes the LLM-wiki pattern into a portable, vendor-neutral format for AI agent knowledge.
The design is intentionally minimal: a directory of markdown files with YAML frontmatter. No schema registry, no central authority, no required tooling.
"If you can
cata file, you can read OKF; if you cangit clonea repo, you can ship it."
Core Concepts
| Concept | Definition |
|---|---|
| Knowledge Bundle | A self-contained directory tree of markdown files. The unit of distribution. |
| Concept | A single unit of knowledge — one markdown file. May describe a table, a metric, a playbook, an API, or any idea. |
| Concept ID | The file path with .md stripped (e.g. tables/users.md has ID tables/users). |
| Frontmatter | YAML block at the top of each file with structured metadata. |
| Body | Standard markdown content after the frontmatter. |
| Link | A markdown link from one concept to another — expresses relationships. |
Reference Files
| Reference | Load when | File |
|---|---|---|
| Spec summary | You need the full OKF v0.1 specification, conformance criteria, and field definitions | references/spec-summary.md |
| Bundle architecture | You're creating or structuring an OKF bundle — directory layout, index files, cross-linking conventions | references/bundle-architecture.md |
| Use cases | You need real-world examples, third-party implementations, and adoption patterns | references/use-cases.md |
Scripts
| Script | Purpose | Load when |
|---|---|---|
okf-bundle-validate.py |
Validate an OKF bundle directory — checks frontmatter, required fields, reserved filenames, and cross-link integrity | You've created or modified an OKF bundle and want to verify conformance |
Assets
| Asset | Purpose | Path |
|---|---|---|
| Concept template | A template markdown file with all recommended frontmatter fields and body sections | assets/concept-template.md |
| Example bundle | A minimal but complete OKF bundle showing directory structure, index files, and cross-linked concepts | assets/example-bundle/ |
Bundle Structure
path/to/bundle/
├── index.md # Optional. Directory listing for progressive disclosure.
├── log.md # Optional. Chronological update history.
├── <concept>.md # A concept at the bundle root.
└── <subdirectory>/ # Subdirectories organize concepts into groups.
├── index.md
├── <concept>.md
└── <subdirectory>/
└── …
Files named index.md and log.md are reserved — they have defined semantics and must not be used for concept documents.
Frontmatter Fields
---
type: <Type name> # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …] # Optional
timestamp: <ISO 8601 datetime> # Optional last-modified time
# … other producer-defined key/value pairs
---
Required: type — a short string identifying the kind of concept. Types are NOT registered centrally. Producers pick descriptive values; consumers tolerate unknown types gracefully.
Conventional body sections:
| Heading | Purpose |
|---|---|
# Schema |
Structured description of an asset's columns/fields |
# Examples |
Concrete usage examples, often as code blocks |
# Citations |
External sources backing claims in the body |
Cross-linking
Concepts link to each other via standard markdown links:
- Absolute (bundle-relative): Begin with
/, relative to bundle root. Recommended — stable when documents move. - Relative: Standard markdown relative paths.
A link from concept A to concept B asserts a relationship. The specific kind (references, depends-on, joins-with) is conveyed by the surrounding prose, not by the link syntax.
Consumers MUST tolerate broken links — a link whose target doesn't exist is not malformed; it may represent not-yet-written knowledge.
Conformance
A bundle is conformant with OKF v0.1 if:
- Every non-reserved
.mdfile contains parseable YAML frontmatter - Every frontmatter block contains a non-empty
typefield - Reserved filenames (
index.md,log.md) follow their defined structure
Consumers MUST NOT reject a bundle for: missing optional frontmatter fields, unknown type values, unknown frontmatter keys, broken cross-links, or missing index.md files.
Relationship to Other Formats
| Format | How OKF Differs |
|---|---|
| Karpathy's LLM Wiki | OKF specifies the interoperability surface — required fields, reserved filenames, conformance criteria |
| Obsidian / Notion vaults | OKF is format-only — no tooling, no runtime, no UI. Any editor works |
| AGENTS.md / CLAUDE.md | OKF is multi-file, hierarchical, cross-linked — not a single convention file |
| Metadata-as-code repos | OKF standardizes the file format so different producers and consumers interoperate |
| Domain schemas (Avro, Protobuf, OpenAPI) | OKF references them — it does not subsume or replace them |
Quick Start
# 1. Create a bundle directory
mkdir my-knowledge && cd my-knowledge
# 2. Create a concept file
cat > datasets/sales.md << 'EOF'
---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
tags: [sales]
timestamp: 2026-06-18T00:00:00Z
---
The sales dataset contains [orders](/tables/orders.md) and [customers](/tables/customers.md).
EOF
# 3. Add an index for navigation
cat > index.md << 'EOF'
# Knowledge Bundle
* Sales Dataset (`datasets/sales.md`) - Retail sales data in an example OKF bundle
EOF
# 4. Validate your bundle
python3 scripts/okf-bundle-validate.py .
Gotchas
- Type values are not registered centrally. Pick descriptive types (
BigQuery Table,Playbook,Metric). Consumers should handle unknown types gracefully. - File path is the identity. Renaming a file changes its concept ID. Use stable paths or add redirects in documentation.
index.mduses no frontmatter (except optionally at the bundle root forokf_version). The body is a markdown list with links.log.mddate headings must be ISO 8601 (YYYY-MM-DD).- Cross-links are untyped. The relationship semantics live in the prose, not in the link syntax. Graph builders treat all links as directed edges.
- OKF does not specify a tag-browsing format. Producers that want tag aggregation should synthesize it at consumption time by scanning frontmatter.
- OKF v0.1 is a draft. The spec will evolve. Minor bumps add backward-compatible features; major bumps may break required fields. Consumers should do best-effort consumption on unknown versions.