FAQ — Open Knowledge Format (OKF)

Frequently asked questions, answered by a human who’s read the spec more times than is probably healthy.

What is OKF?

A folder of Markdown files that represents what your organization knows — tables, metrics, APIs, playbooks, whatever — in a way both humans and AI agents can understand without special tools.

Each .md file is a “concept.” YAML frontmatter at the top holds metadata. The structure is hierarchical and git-friendly. That’s mostly it.

Three mandatory rules:

1. Every .md (except index.md and log.md) needs parseable YAML frontmatter
2. Every frontmatter needs a non-empty type field
3. Reserved files (index.md, log.md) follow a defined structure

Everything else is up to you.

Who created OKF?

Sam McVeety and Amir Hormati (Tech Leads, Data Analytics Engineering, Google Cloud) designed and announced OKF on June 12, 2026 via the Google Cloud Blog.

Published under Apache 2.0 in the GoogleCloudPlatform/knowledge-catalog repo.

Born inside the Knowledge Catalog (formerly Dataplex) world, but the spec is vendor-neutral. No Google Cloud required. Any org can adopt it.

Current version: 0.1 (Draft). Early, but usable today.

What’s the “LLM Wiki” pattern?

OKF formalizes a pattern that keeps reappearing under different names: the idea of giving AI agents a shared markdown library that grows more useful over time.

Andrej Karpathy articulated it most crisply in his LLM Wiki gist: “LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass.” The bookkeeping that causes humans to abandon personal wikis is exactly what LLMs are good at.

The same idea appears as Obsidian vaults wired to coding agents, the AGENTS.md / CLAUDE.md family of convention files, repos full of index.md and log.md artifacts, and “metadata as code” repositories inside data teams.

The problem: each instance is bespoke. Karpathy’s wiki and your team’s wiki may look alike (markdown, frontmatter, cross-links), but none are designed to cooperate. There’s no agreed-upon answer to what fields every document should carry.

OKF is the missing interoperability layer. It pins down the minimal set of conventions so wikis written by different producers can be consumed by different agents without translation.

Do I need an SDK?

No. If you need an SDK to write Markdown files, we have bigger problems to discuss.

The spec literally says: “If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

To produce it: text editor. To consume it: eyes. To validate: check 3 rules.

Tooling exists (validators, generators). None of it is required.

How is it different from AGENTS.md?

Different jobs entirely.

AGENTS.md tells an agent how to behave. OKF tells an agent what exists in the world.

They’re friends, not competitors. Your AGENTS.md can say “check the OKF bundle at /knowledge for domain context.”

How does it compare to Obsidian?

Same DNA (Markdown + frontmatter + links), different species.

Obsidian = personal knowledge tool. Wikilinks, graph view, plugins. Built for one human’s brain.

OKF = interchange spec. Built so Team A’s knowledge survives the trip to Team B (or Agent C) intact. Think: the difference between your personal notebook and a published reference manual.

Key differences: OKF uses standard Markdown links (not [[wikilinks]]), mandates a type field, has reserved files with defined structure, and is designed for programmatic consumption.

You can edit OKF bundles in Obsidian. They’ll coexist peacefully. Just don’t expect OKF to generate a pretty graph for you.

What about DESIGN.md?

DESIGN.md is a document. OKF is a format.

If you converted your DESIGN.md into OKF, it’d become one concept in a bundle — maybe type: Architecture Decision. OKF is the container; DESIGN.md is something that lives inside it.

That’s really all there is to say here.

Does it work with Claude/GPT/Gemini?

Yes. All of them. Any LLM that can read text — so, all of them — handles OKF natively.

• Claude/Cursor: Drop the bundle in project context. Done.
• GPT/ChatGPT: Upload the .md files or ZIP them.
• Gemini: Natural fit via Knowledge Catalog, but works standalone too.
• Any MCP agent: Serve the bundle as a resource.

Model agnosticism is a foundational requirement of the spec. No lock-in.

How do I validate a bundle?

Check 3 things:

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

That’s the whole spec compliance check. Here’s a one-liner if you want:

for f in $(find ./bundle -name "*.md" ! -name "index.md" ! -name "log.md"); do
  head -50 "$f" | grep -q "^type:" || echo "FAIL: $f missing type"
done

A client-side validator is available at /validator. But honestly, the bash loop above gets you 90% there.

Will OKF replace data catalogs?

No. The spec explicitly lists this as a non-goal.

Catalogs = platforms (UI, API, governance, lineage, permissions). OKF = export/exchange format.

Your catalog is the system of record. An OKF bundle is the portable snapshot you version in git, share across teams, or feed to an AI agent. Different layers, complementary roles.

Is it only for BigQuery?

The examples use BigQuery because that’s where it was born. The format doesn’t care.

type: PostgreSQL Table       # fine
type: API Endpoint           # fine
type: Runbook                # fine
type: Your Mom's Recipe      # technically valid

The type field is free-form. The optional resource field is a generic URI — point it at Grafana, Snowflake, Confluence, whatever. OKF documents any organizational knowledge, not just data assets.

How do I contribute?

1. Repo: GoogleCloudPlatform/knowledge-catalog
2. Open issues, submit PRs, contribute examples in samples/ and toolbox/
3. License: Apache 2.0

It’s v0.1 Draft — the best possible time to shape where it goes. There’s a CONTRIBUTING.md in the repo.

Do I need a backend?

No. A bundle is a folder of .md files.

Serve it with any static file server. Version it with git. Distribute it as a ZIP. The validator runs client-side in the browser. Zero databases, zero APIs, zero infra.

If you want to build on top of OKF (search, enrichment, a UI), that’s your call. But the format itself is pure filesystem. Refreshingly boring technology.

Does it work with git?

It works beautifully with git. In fact, git is the recommended distribution method.

• Markdown = clean diffs
• Commit history = who changed what concept and when
• Branches = propose knowledge changes via PR
• git clone = you have the entire bundle

The spec’s log.md is slightly redundant if you use git (commit log does the same job), but it’s there for when bundles travel without VCS history.

Git + OKF = organizational knowledge managed with the same practices we already use for code. Nothing new to learn.

What’s the future of OKF?

⚠️ Opinion — speculation ahead, not confirmed roadmap.

It’s v0.1 Draft. Google Cloud is testing the waters.

My read on what’s likely:

Short term: Knowledge Catalog integration, official CLI/validator, MCP support for serving bundles to agents.

Medium term: other providers adopt or create compatible formats, enrichment agents auto-generate bundles, maybe a public bundle registry.

My bet (opinion): OKF could become the “Markdown of organizational knowledge.” Same playbook — wins by being dead simple and universal. The timing is right: agents need structured context, the market is fragmented across proprietary solutions, and the spec has zero barriers to adoption.

The risk (also opinion): if Google doesn’t push cross-cloud adoption, it joins the graveyard of Google formats nobody asked for. But Apache 2.0 + vendor-neutral design help.

Practical advice: just start using it. The cost is literally zero — it’s Markdown files in a folder. Worst case, you have well-organized documentation.

OKF vs llms.txt vs schema.org?

Three specs, three jobs, zero conflict.

Bottom line: They stack, they don’t compete. schema.org tells Google what your page is. llms.txt tells AI crawlers where to go. OKF tells your agents what your org knows. Use all three.

Your llms.txt can link to a public OKF bundle. Your schema.org can describe assets documented in OKF. They’re layers in the same cake.

Can I sell OKF bundles?

There’s no technical or legal reason you can’t. Apache 2.0 governs the spec, not what you produce with it.

Lawyers packaging case-law bundles. SEOs selling industry keyword knowledge. Data teams distributing curated domain models. Analysts shipping research as structured OKF. All technically feasible today.

What’s missing: there’s no registry, no licensing convention, no discovery layer for commercial bundles. You’d sell it the same way you sell any digital asset — Gumroad, a private repo, a ZIP behind a paywall.

My take: someone will build “npm for OKF bundles” within a year. The format is too composable not to become a marketplace eventually. For now, you’re early — sell it however works.

How do agents discover my OKF?

There is no official discovery mechanism yet. OKF bundles are explicitly loaded, not crawled.

Today, the most common patterns:

1. llms.txt — link to your bundle in the # Knowledge section
2. auth.md — reference OKF path in your repo’s agent instructions
3. .well-known/okf — convention some teams are adopting (not standardized)
4. MCP server card — expose bundle location in your MCP manifest
5. Direct path — agent config says “load /knowledge” and you’re done

My take: discovery will probably converge on llms.txt for public bundles and MCP manifests for private ones. But right now it’s intentionally explicit. You tell the agent where the knowledge is. The agent doesn’t guess.

This is a feature, not a bug. You want to control which agents get which knowledge.

Does OKF replace RAG?

No. But it changes what RAG has to work for.

Known facts (your org’s structure, APIs, metrics, runbooks) → OKF. Direct read. No embedding, no retrieval, no hallucination risk.

Dynamic queries (searching across 10k documents, fuzzy matching, “find me something like X”) → RAG. Still needed.

Karpathy’s framing is useful here: build the knowledge artifact once and read it directly, rather than re-deriving it from scattered documents every time an agent needs context.

Bottom line: OKF handles the “known knowns.” RAG handles the “I know it’s somewhere.” Use both. Your RAG pipeline can index OKF bundles too — they’re just clean Markdown, which is ideal input for chunking.

What’s the W3C doing with OKF?

The Holon Community Group launched on June 19, 2026, with 30+ participants. It’s exploring how OKF concepts map to existing web standards.

Key development: DataBook — a W3C profile that adds formal semantics on top of OKF bundles:

• IRI identifiers for concepts (globally addressable)
• RDF compatibility (concepts become linked data)
• SPARQL queryability (ask your bundle structured questions)
• SHACL validation (enforce shape constraints beyond OKF’s 3 rules)

The good news: the “format, not platform” principle is preserved. DataBook is an optional layer. Plain OKF bundles remain valid. You add formal semantics only when you need interop with the semantic web stack.

My take: This is how OKF avoids becoming another Google-only format. W3C engagement signals long-term commitment to open governance. Whether most teams will need RDF/SPARQL is another question — but having the bridge ready matters for enterprise adoption.

What if Google abandons OKF?

Honest answer: it’s a real risk. Google’s product graveyard is famous for a reason.

Risk factors:

• Single-vendor origin story
• Google’s track record with open formats (AMP, anyone?)
• v0.1 Draft — could stall before reaching 1.0

Mitigating factors:

• Apache 2.0 license — anyone can fork and maintain
• The format is just Markdown files. Zero proprietary tooling
• W3C Holon CG provides independent governance
• Cost zero in, cost zero out — no vendor dependency to unwind

Bottom line: Even if Google walks away tomorrow, your OKF bundles are still a folder of well-organized Markdown with YAML frontmatter. That’s useful regardless of who maintains the spec. The worst-case scenario is “you have good documentation.” There are worse fates.

The real question isn’t “what if they abandon it?” — it’s “is the format useful enough that the community maintains it independently?” Given that it’s literally just Markdown conventions… yes.

OKF vs knowledge graph?

OKF is implicitly a graph. A knowledge graph is formally a graph.

OKF is graph-adjacent. Your concepts link to each other. Those links form a graph implicitly. But you can’t run SPARQL on raw OKF — you’d need the DataBook profile (W3C layer) for that.

My take: If you need formal reasoning (“find all APIs that depend on deprecated tables three hops away”), build a knowledge graph. If you need “give my agent context about our domain,” OKF is simpler and sufficient. Many teams will do both — OKF as the authoring layer, KG as the inference layer.

Does OKF help with SEO?

No. Google has been explicit about this: OKF is not a search ranking signal.

For SEO, use:

• schema.org — structured data for rich results
• llms.txt — help AI crawlers navigate your site
• Clean content — well-structured HTML, proper headings, fast pages

OKF is internal agent knowledge. It’s designed for your AI systems, not for Google’s crawler. It lives in your repo or behind auth — search engines never see it.

Don’t confuse “made by Google” with “helps you rank on Google.” Different teams, different goals.

Bottom line: OKF makes your agents smarter. schema.org makes your pages richer in SERPs. They solve completely different problems. See the OKF vs llms.txt vs schema.org comparison above.

How does OKF work with MCP?

kcmd (the OKF CLI) is already an MCP server. Plug it into any MCP-compatible agent and it gets native OKF operations.

Available tools:

MCP config example:

{
  "mcpServers": {
    "okf": {
      "command": "kcmd",
      "args": ["mcp", "--bundle", "./knowledge"]
    }
  }
}

Beyond kcmd, any MCP server can expose an OKF bundle as resources. The concepts are just files — serve them as resource:// URIs and any MCP client can read them.

My take: MCP + OKF is the cleanest integration path. Your agent asks for knowledge via tool calls, gets structured Markdown back. No custom API, no embedding pipeline, no special protocol. It just works because both sides agreed that “files with frontmatter” is a perfectly good data format.

More questions?

• 📖 Official spec: github.com/GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md
• 🌐 Reference site: okf.md
• 🛠️ Validator: coming soon