Open Knowledge Format (OKF): Adopt Markdown Knowledge Bundles for AI Agents?

When teams start feeding Markdown vaults and internal docs into AI agents, the pain rarely comes from the .md extension itself. It comes from mixing operational contracts, procedures, durable domain facts, and raw source material in the same layer. Context bloat and unclear trust boundaries follow.

📑Table of Contents

1. The OKF v0.1 minimum contract
2. OKF v0.2 trust signals for agent-written corpora
3. What hands-on work revealed: fit rate and visualizer traps
4. Comparison: OKF vs MCP vs AGENTS.md vs RAG
5. Adoption checklist and next actions
6. Author Perspective
7. FAQ
8. Summary

What OKF is

Open Knowledge Format (OKF), published by Google Cloud, is a minimal vendor-neutral contract for shipping curated static knowledge as Markdown + YAML directory bundles.

OKF is not:

• a wiki product
• a live-tool runtime
• a substitute for repository behavior contracts

This article combines the official v0.1/v0.2 posts with independent hands-on notes so you can decide: adopt, wait, or solve the pain in another layer.

---

What you will learn

---

The OKF v0.1 minimum contract

Problem and scope

OKF v0.1 is intentionally small: just markdown, just files, just YAML. No required SDK, runtime, or custom compression.

In the Google Cloud Blog post (Sam McVeety & Amir Hormati, 2026-06-12), the problem statement is fragmented agent context.

Examples include catalog APIs, wikis, shared drives, comments, and tacit knowledge that agents reassemble every time.

---

Format rules

The format nails a few rules:

• One concept = one file
• Path is the Concept ID
• Ordinary Markdown links form the graph
• The only always-required frontmatter field is type (no central registry)
• Common optional fields: title, description, resource, tags, timestamp
• Reserved files: index.md for progressive disclosure, log.md for history

---

Principles and reference tooling

Three principles matter for adoption:

• minimally opinionated
• producer–consumer independence
• format not platform

Reference tooling ships as a proof of concept under GitHub GoogleCloudPlatform/knowledge-catalog in the OKF tree:

• a BigQuery enrichment agent
• a static HTML visualizer
• sample bundles (GA4, Stack Overflow, Bitcoin)

Knowledge Catalog can ingest bundles and serve them to agents, but the format itself is not GCP-locked.

---

Independent confirmation

Independent coverage matches the skeleton from other angles.

• MarkTechPost frames OKF as a vendor-neutral markdown spec for curated agent context
• Qiita @zumax restates SPEC terms (Knowledge Bundle / Concept / Concept ID) and the permissive consumer model: unknown types and broken links should not cause hard rejection

That design makes incremental adoption realistic—add type to existing Markdown first.

Source

---

OKF v0.2 trust signals for agent-written corpora

Why trust becomes the main question

After v0.1, the hard question is trust. When agents write thousands of concepts, the implicit accountability of human-authored pages disappears.

The Google Cloud Blog post on OKF v0.2 (2026-07-24) adds optional frontmatter signals for five questions.

---

Five opt-in trust questions in v0.2

1. Provenance — what produced this (sources and credibility hints such as author / usage_count / last_modified). There is no single global score field.
2. Trust — separate generated (by/at) from verified (list of by/at). Example tiers: unverified / machine-confirmed / human-reviewed.
3. Freshness — stale_after as an absolute date.
4. Lifecycle — status: draft → stable → deprecated (default stable when omitted).
5. Attestation — Attested Computation type with executor receipt + deterministic attester; evaluated at runtime and not stored as a permanent bundle score substitute.

---

Compatibility and operational filters

Compatibility is practical:

• type remains the only always-required field
• valid v0.1 bundles remain valid
• renames include timestamp → generated.at and Citations lists → sources with fallback
• the acme_retail companion sample and visualizer displays for tier/status/staleness are part of the update

Operationally:

• filter verified definitions away from unverified generated notes
• do not collapse attestation and verification into one boolean

Attestation answers “was this number produced by an approved computation path?” Verification answers “has this definition been reviewed?”

---

What hands-on work revealed: fit rate and visualizer traps

DevelopersIO fit rate and visualizer traps

Specs understate migration cost. Classmethod DevelopersIO (2026-06-16) independently wrote a minimal bundle, ran the visualizer, and measured an existing Obsidian vault.

---

Hands-on measurements

• Handwritten minimal bundle reached Concept 3/3 conformance
• GA4 sample visualization: 11 concepts / 9 edges / ~50KB HTML
• Trap: SPEC-friendly absolute paths such as /tables/customers.md are skipped as edges in enrichment_agent viewer/generator.py when links start with :// or /
• Relative links produced a connected graph (3 concepts / 5 edges in their corrected case)
• Among 812 Obsidian .md files: 206 already OKF-conformant (25.4%), 487 lacked frontmatter (60%), 119 lacked type (14.7%); 606 were candidates if type were added

---

Reference agent vs handwritten path

The enrichment agent assumes BigQuery + Gemini. AWS-centric teams may still get value from handwritten bundles plus the visualizer without adopting the full reference agent path.

---

Concept extraction and role mixing

Marie Haynes (2026-06-16) stresses concept extraction over page dumps: one source page can become multiple concepts.

• YAML acts like an index card; the body stays free-form
• Progressive disclosure avoids stuffing whole corpora into context
• She also reports an early prototype OKF “brain” queried with Gemini on a tiny set of documents

Zenn m2lab frames Markdown debt as role mixing:

• procedures mixed with facts
• repo operating contracts mixed with domain knowledge
• raw material mixed with compiled knowledge

Vacuuming everything into OKF creates a second bloat curve. Do not write rotting live state into static files.

---

Low-cost experiments

Three low-cost experiments:

1. Count how many files in a representative vault already have type frontmatter
2. If you use the visualizer, standardize on relative links
3. Split only three concepts with a true one-concept-per-file boundary

For the adjacent design question of human vaults versus agent memory layers, see Separating human vaults from AI memory layers.

---

Comparison: OKF vs MCP vs AGENTS.md vs RAG

Stack, not competition

These layers stack. They are not competing products for the same job.

---

Comparison table: static knowledge and live tools

Layer	Primary question	Typical home	Relationship to OKF
OKF	What curated domain facts should agents reuse?	Markdown+YAML knowledge bundle	Focus of this article; static contract with required type
MCP	What can be done right now?	Live tools / servers	Do not encode rotting live state in OKF
AGENTS.md / Skills	How should the agent behave?	Repo operating contracts / procedures	Do not absorb behavior contracts into OKF

---

Comparison table: retrieval and entry maps

Layer	Primary question	Typical home	Relationship to OKF
RAG / raw corpus	What can we retrieve before concepts are clear?	Search indexes / source text	Raw layer before concept boundaries
llms.md-style maps	Where is the entry map?	Short root indexes	Complements OKF index.md progressive disclosure

---

Sources for the comparison

Sources (as of June–July 2026):

• Google Cloud OKF v0.1
• DevelopersIO hands-on
• Zenn m2lab

---

Decision rules and adjacent topics

Decision rules:

• Live privileged operations → MCP
• Team behavior and hard stops → AGENTS.md / skills
• Reusable definitions, metrics, table semantics → OKF candidate
• Fuzzy concept boundaries → keep as RAG/raw while inventorying

Loop/harness design remains a separate axis:

• AI agent loop and harness design
• building a custom harness with Pi Coding Agent

OKF decides what static knowledge to pass; harness design decides how the loop runs and where it stops.

Tooling choices such as the ax CLI for agent-oriented HTML fetch/extract should also stay on their own checklist.

---

Adoption checklist and next actions

Lean adopt when

• Domain facts are re-translated across multiple agent tools
• Your notes culture already uses frontmatter/type (the ~25% fit example is a useful prior, not a guarantee)
• You want progressive disclosure instead of full-corpus context dumps
• You need generated vs human-reviewed separation via v0.2-style signals

---

Lean wait / use another layer when

• The pain is live operations, authz, or real-time state → MCP first
• The pain is repo behavior contracts → AGENTS.md/skills first
• You refuse handwritten bundle operations and also refuse GCP-leaning reference paths

---

Checklist for this week

• ✓ List 10 “read first” files and label each as contract / procedure / fact / raw
• ✓ Move only domain facts into a temporary knowledge/ area and add type:
• ✓ Create one index.md entrypoint for progressive disclosure
• ✓ Normalize links to relative paths and verify edges in the visualizer
• ✓ If agents write concepts, write a one-pager for generated / verified / stale_after policy
• ✓ Keep rotting live data out of files; put it behind MCP

---

What not to do

• Do not migrate an entire vault because a topic is trending
• Do not decide from a single secondary recap
• Ground numbers and traps in the official posts plus at least one independent hands-on or analysis

---

Author Perspective

The useful question is not “is OKF new?” but “which layer is actually hurting?”

• High translation cost for durable facts points to OKF
• Privilege-bound live actions point to MCP
• Unstable team behavior points to AGENTS.md/skills first

Adding type and validating relative-link graphs is a low-lock-in entry path. Dumping unscoped raw corpora into bundles usually recreates bloat under a new name.

---

FAQ

Q1. Is OKF Google Cloud-only?

The format is vendor-neutral files. Reference agents and Knowledge Catalog flows are GCP-leaning, but handwritten bundles and the visualizer can still validate the contract.

---

Q2. What metadata is required?

Only type is always required in v0.1 and v0.2. Trust fields in v0.2 are opt-in.

---

Q3. Should AGENTS.md and skills move entirely into OKF?

No. Keep behavior/procedures in repo contracts and durable domain facts in OKF. Absorbing everything recreates bloat.

---

Q4. Can an Obsidian vault be used as-is?

Notes with type frontmatter are already close. In the DevelopersIO example, about 25.4% of 812 files were already conformant, with many more reachable by adding type.

---

Q5. Are absolute-path links safe?

Even when SPEC discussion favors them, the reference visualizer path skips /-prefixed links as edges. Prefer relative links when checking the graph.

---

Q6. Is a popular secondary article enough evidence?

Useful as discovery context. For implementation decisions, use Google Cloud official posts plus independent hands-on/analysis.

---

Related articles:

• 13580
• 13621

Summary

OKF is a minimal static-knowledge contract for agents, not a platform replacement and not an MCP replacement. v0.1 defines shape; v0.2 adds trust/freshness/lifecycle signals while keeping v0.1 bundles valid.

A practical sequence is:

1. label roles
2. cut a few typed concepts
3. verify relative links in the visualizer
4. write a one-page trust/freshness policy for generated content

Keep popularity signals out of the decision core.