Open Knowledge Format (OKF)

OKF is a vendor-neutral, open spec (v0.2) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can cat a file, you can read OKF.

It formalizes the "LLM Wiki" pattern (Karpathy's gist) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.

For the full spec, see references/spec-v02.md.

Design Principles

1. Minimally opinionated — Only type is required. The spec defines interoperability surface, not content model.
2. Producer/consumer independence — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
3. Format, not platform — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.

---

Key Terminology

• Bundle — A directory tree of .md files. The unit of distribution (git repo, tarball, or subdirectory).
• Concept — One markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
• Concept ID — File path within the bundle, minus .md suffix. Example: tables/users.md → ID tables/users
• Frontmatter — YAML block between --- delimiters at file top.
• Body — Everything after the frontmatter. Standard markdown.
• Link — Standard markdown link expressing a relationship between concepts.
• Citation — Link to an external source backing a claim in the body.
• Source — Material a concept derives from, recorded in frontmatter sources.
• Actor — A tool, process, or human recorded in generated.by or verified[].by.

---

Quick Reference — Frontmatter Fields

Field	Required?	Description
type	YES	Kind of concept (free-form string, e.g. BigQuery Table, Metric, Playbook, API Endpoint)
title	Recommended	Human-readable display name
description	Recommended	One-sentence summary
resource	Recommended	URI identifying the underlying asset (omit for abstract concepts)
tags	Optional	YAML list for cross-cutting categorization
sources	Optional	Provenance entries; resource is required within each entry
generated	Optional	Producer actor and time of the current representation
verified	Optional	Actual verification events; drives the derived trust tier
status	Optional	draft, stable, or deprecated; absent means stable
stale_after	Optional	Absolute YYYY-MM-DD staleness date

Additional producer-defined keys are allowed. Never reject unknown fields.

Reserved Filenames

File	Purpose	Has frontmatter?
index.md	Directory listing for progressive disclosure	NO*
log.md	Change history, newest first	NO

*Exception: bundle-root index.md MAY have frontmatter with okf_version: "0.2" to declare spec version.

Conventional Body Headings

Heading	When to use
# Schema	Data assets — describe columns/fields
# Examples	Show concrete usage (code blocks, queries)
# Computation	Sanctioned computation for an Attested Computation concept

---

Create a Bundle

When the user wants to create an OKF bundle from scratch:

1. Determine scope and structure

Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.) Organize into a directory tree that makes sense for the domain.

2. Create concept documents

Each concept = one .md file. Minimal conformant example:

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas]
generated: { by: "process:metric-catalog", at: "2026-06-13T10:00:00Z" }
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

For more examples across domains, see references/examples.md.

3. Cross-link concepts

Use standard markdown links. Two forms:

• Absolute (bundle-relative, starts with /): [customers](/tables/customers.md) — preferred (stable when files move)
• Relative: [churn](./churn.md)

Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.

4. Generate index.md

Place in any directory for progressive disclosure. No frontmatter. Format:

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

Entries should include the description from the linked concept's frontmatter.

5. Generate log.md (optional)

Chronological change history, newest first, ISO 8601 date headings:

# Update Log

## 2026-06-13
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-06-10
- **Initialization**: Bundle created.

The bold leading word (**Update**, **Creation**, **Deprecation**) is convention, not requirement.

6. Declare version (optional)

Bundle-root index.md may include frontmatter declaring the spec version:

---
okf_version: "0.2"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

This is the only place frontmatter is permitted in an index.md.

7. Distribution

A bundle can be distributed as:

• A git repository (recommended — history, attribution, diffs)
• A tarball or zip archive
• A subdirectory within a larger repository

8. Verify conformance

Three rules — all must pass:

1. Every non-reserved .md file has parseable YAML frontmatter
2. Every frontmatter has a non-empty type field
3. Reserved files (index.md, log.md) follow their defined structure when present

---

Validate a Bundle

Preferred: okflint (when available)

okflint is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.

Agent behavior: Before validating, check if okflint is installed (command -v okflint). If NOT installed, ask the user:

"okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:

1. uv tool install okflint (recomendado, isolado)
2. pip install okflint
3. Seguir sem ele (validação básica com o script bash embutido)"

If the user agrees to install:

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

After installation (or if already available):

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

okflint advantages over the built-in script:

• Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
• Wikilink resolution against full Obsidian vault
• JSON output (--json) for CI pipeline parsing
• Detects broken markdown links and ambiguous wikilinks
• Exit codes: 0 = pass, 1 = conformance failure, 2 = bad manifest

Fallback: built-in bash script

When okflint is not installed, use scripts/validate.sh which checks the 3 core conformance rules.

When asked to validate, check the 3 conformance rules. Report:

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)

For a script-based check, see scripts/validate.sh.

Errors (conformance failures)

• E1: File {path} has no YAML frontmatter
• E2: File {path} has frontmatter but no type field (or empty)
• E3: Reserved file {path} has unexpected structure

Warnings (non-blocking, spec allows these)

• W1: Missing recommended field title or description
• W2: Broken cross-link {link} in {file}
• W3: No generated field
• W4: No index.md in directory {dir}
• W5: log.md dates not in ISO 8601 format

Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.

---

Enrich Concepts

When the user has existing OKF concepts that need enrichment:

Add schema section

For data assets, add # Schema with a columns table:

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |

Add examples section

For APIs, queries, or tools, add # Examples with fenced code blocks showing usage.

Add provenance and claim attribution

When claims derive from sources, add one sources entry per concrete source. Give claim-bearing entries stable IDs and use matching keyed Markdown footnotes:

---
type: Playbook
sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official documentation
---

Follow the documented procedure.[^official-docs]

[^official-docs]: [Official documentation](https://example.com/docs)

Source resources may be absolute URLs, bundle-relative paths, paths into a references/ subdirectory, or scope descriptors permitted by the spec.

Add cross-links

Weave links into natural prose. Don't create a standalone "links" section — express relationships in context where they're meaningful.

Fill recommended fields

If title, description, tags, or warranted generated metadata are missing, add them. Derive values from body content when possible, but never invent actors or verification events.

Enrichment workflow reference

The official enrichment agent follows this pattern — apply the same logic manually:

1. Start with metadata-only docs (just frontmatter + minimal body)
2. Add schema/structure from source system
3. Add citations from authoritative documentation
4. Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
5. Generate index.md files for progressive disclosure

---

Convert Sources to OKF

For detailed conversion guides, see references/conversion.md.

Quick rules

Notion export: Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.

Obsidian vault: Convert [[wikilinks]] → [title](./file.md). Ensure type field exists. Move inline #tags to frontmatter.

CSV/spreadsheet: Each row = one concept. Map columns to frontmatter fields. First column = filename.

---

Guardrails

1. NEVER invent data. If you don't know the correct type, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
2. Preserve unknown fields. OKF explicitly allows extension. Don't delete fields you don't recognize.
3. Don't impose taxonomy. Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
4. Broken links are OK. The spec explicitly permits them — they represent not-yet-written knowledge.
5. Minimal by default. Generate only type (required) + recommended fields that are warranted. Don't pad with empty values.
6. Ask before assuming. If the domain is unclear, ask what types and structure make sense.

---

Serve via Google Cloud Knowledge Catalog

Google Cloud's Knowledge Catalog natively ingests OKF bundles and serves them to agents. This is the enterprise path — optional but powerful.

kcmd CLI (Metadata as Code)

kcmd is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think "git for metadata."

# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>

# Pull current state from catalog
kcmd pull

# Push local changes
kcmd push --dry-run
kcmd push

Also ships as an MCP server for agent integration:

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

MCP tools: pull, push, list-entries, lookup-entry, modify-entry.

Reference Enrichment Agent

The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:

1. BQ pass — one OKF doc per table/view from metadata
2. Web pass — LLM crawls seed URLs and for each page decides to:
   • (a) Enrich existing concepts with citations/schemas
   • (b) Mint a new references/<slug> doc
   • (c) Skip irrelevant content

Controls: --web-seed-file, --web-max-pages, --web-allowed-host, --no-web.

When to mention this to users: If they're enriching BigQuery datasets, point them to the reference agent. If they want enterprise catalog integration, point to kcmd and the ingest demo.

---

Output Format

When creating a bundle, present results as:

1. Directory tree showing the full structure
2. Each file's content in fenced code blocks
3. Conformance check confirming the bundle passes the 3 rules

saas-metrics/
├── index.md
├── log.md
├── mrr.md
├── churn.md
└── nps.md

Then show each file, then confirm: "Bundle is OKF v0.2 conformant ✅"