What it is: OKF is Google Cloud’s open-standard format for organizational knowledge — published June 2026 by Sam McVeety and Amir Hormati, licensed Apache 2.0. Source: GoogleCloudPlatform/knowledge-catalog.

Problem: Your agents don’t know your organization. They can reason, write code, and summarize text — but only with the right internal context. That context lives everywhere and belongs nowhere: schema docs in BigQuery, metric definitions in a Confluence wiki, join logic in a senior engineer’s head, runbooks in a shared drive nobody maintains.

Every AI agent builder has been solving this context-assembly problem from scratch. Every data catalog vendor has been reinventing the same data models. The result is a sea of bespoke, siloed, non-portable “LLM wikis” — your team’s Obsidian vault works for your agents, but nobody else’s.

Solution: Open Knowledge Format (OKF) — the fix isn’t a new platform, it’s a format. A small, stable, agreed-upon set of conventions that makes a knowledge corpus self-describing, so any producer can write it and any consumer can read it.

The Core Principle: Intentionally Minimal

OKF is exactly what it says on the tin — markdown files with YAML frontmatter, organized in a directory. No schema registry. No central authority. No required SDK. No proprietary API standing between you and your metadata.

The design bet is explicit: broad, low-friction adoption of a simpler format produces more organizational value than narrow, high-friction adoption of a richer one. One required field. Everything else is optional or convention.

The Missing Knowledge Layer

OKF formalizes the knowledge layer between raw data (data catalogs, databases) and agent reasoning (prompts, LLM execution):

┌────────────────────────────────────────────────────────┐
│                   Agentic AI Client                    │
└───────────────────────────┬────────────────────────────┘
                            ▼
┌────────────────────────────────────────────────────────┐
│    OKF Context Layer (Self-Describing Memory Graph)    │
│  [index.md] --> [concepts/schema] --> [playbooks/run]  │
└───────────────────────────┬────────────────────────────┘
                            ▼
┌────────────────────────────────────────────────────────┐
│     Raw Data Infrastructure (Databases, API Docs)      │
└────────────────────────────────────────────────────────┘

An OKF bundle functions as structured external memory — persisted, version-controlled, traversable, and agent-navigable via index.md hierarchies. It’s neither a vector store nor a graph database; it’s a knowledge corpus that any agent with file read access can traverse.

Spec Breakdown

Key Terms

Bundle Structure

A bundle is a plain directory tree:

path/to/bundle/
├── index.md            <- Optional. Directory listing for progressive disclosure.
├── log.md              <- Optional. Chronological change history.
├── <concept>.md        <- A concept at the root.
└── <subdirectory>/
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── ...

Distribution options (in descending preference):

• Git repository — gives history, attribution, diffs, PR reviews for free
• Tarball / zip archive
• Subdirectory within a larger monorepo

Reserved filenames: index.md and log.md have defined meaning at any level and must not be used for concept documents.

Concept Documents

Every concept is a UTF-8 markdown file with two parts: a frontmatter block and a body.

Frontmatter:

---
type: <Type name>          # REQUIRED — the only required field
title: <display name>      # Recommended
description: <one-liner>   # Recommended — used for index snippets and search
resource: <URI>            # Recommended — canonical URI of the underlying asset
tags: [tag1, tag2]         # Optional
timestamp: 2026-05-28T14:30:00Z  # Optional — ISO 8601, last meaningful change
# ...any additional producer-defined keys are valid
---

The only required field is type. It’s a free-form string — values like BigQuery Table, API Endpoint, Metric, Playbook, Reference are illustrative, not registered. Consumers must tolerate unknown types gracefully.

Body — conventional headings:

Cross-Linking

Concepts link to each other via standard markdown links — this is how the knowledge graph is formed.

Absolute (bundle-relative) — preferred:

See the [customers table](/tables/customers.md) for the join key.

Relative:

See the [neighboring concept](./other.md).

Link semantics are deliberately loose — a link from A to B asserts a relationship. The specific kind (references, joins-with, depends-on) is expressed in the surrounding prose. Broken links are valid; a link to a not-yet-written concept is not malformed.

Index Files

index.md can appear at any directory level for progressive disclosure:

# Tables

* [Customer Orders](/tables/orders.md) - one row per completed order
* [Customers](/tables/customers.md) - one row per registered customer

# Datasets

* [Sales Dataset](/datasets/sales.md) - all sales-related tables

Log Files

log.md tracks changes chronologically. Newest entries first:

# Directory Update Log

## 2026-05-22
* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

Conformance

A bundle is conformant with OKF v0.1 if:

1. Every non-reserved .md file contains a parseable YAML frontmatter block.
2. Every frontmatter block contains a non-empty type field.
3. index.md and log.md, when present, follow the structures above.

Consumers must not reject a bundle because of: missing optional frontmatter fields, unknown type values, unknown additional keys, broken cross-links, or missing index.md files. This tolerance is intentional — brittle consumers would poison the ecosystem.

Enterprise Use Case: Customer Success & Data Alignment

Scenario: Align Customer Success runbooks with Data Engineering database schemas, enabling an on-call AI support agent to automatically triage alert escalations.

cs-eng-bundle/
├── index.md
├── log.md
├── datasets/
│   └── customer_behavior.md
├── tables/
│   ├── index.md
│   └── subscription_events.md
└── playbooks/
    └── churn_triage.md

1. Root Directory Navigation (index.md)

---
okf_version: "0.1"
title: "Customer Success & Data Engineering Catalog"
description: "Cross-functional knowledge index mapping customer metrics to telemetry tables"
---

# Datasets
* [Customer Behavior Dataset](/datasets/customer_behavior.md) - Aggregates application usage and user states.

# Tables
* [Subscription Events Table](/tables/subscription_events.md) - Transactional logs for stripe and app store events.

# Playbooks
* [Churn Triage Runbook](/playbooks/churn_triage.md) - Actionable steps when customer churn rates spike.

2. Dataset Definition (/datasets/customer_behavior.md)

---
type: Dataset
title: Customer Behavior Data
description: Unified business view tracking user subscription cycles and behaviors.
resource: https://console.cloud.google.com/datacatalog/customer_behavior
tags: [marketing, analytics, customers]
timestamp: 2026-06-15T09:00:00Z
---

# Overview
This dataset contains cleaned, sessionized user events and transactional logs designed
to compute user engagement and retention. It is the authoritative source for the Churn Prediction Model.

# Tables Included
* [Subscription Events](/tables/subscription_events.md) - Captured transactional events for subscription state changes.

3. BigQuery Table Schema (/tables/subscription_events.md)

---
type: BigQuery Table
title: Subscription Events Raw
description: Transactional logs mapping payment state transitions.
resource: https://console.cloud.google.com/bigquery?p=prod-data&d=raw_events&t=subscription_events
tags: [finance, raw-telemetry]
timestamp: 2026-06-17T14:30:00Z
---

# Schema

| Column | Type | Description |
| :--- | :--- | :--- |
| `event_id` | STRING | Unique event identifier. |
| `customer_id` | STRING | Unique system user ID. |
| `event_type` | STRING | Event action: SUBSCRIBE, RENEW, CANCEL, or EXPIRE. |
| `amount_usd` | NUMERIC | Transaction value in USD. |
| `timestamp` | TIMESTAMP | Event creation time (UTC). |

# Examples

## Querying Cancellation Trends
```sql
SELECT
  DATE(timestamp) as event_date,
  COUNT(DISTINCT customer_id) as cancel_count
FROM `prod-data.raw_events.subscription_events`
WHERE event_type = 'CANCEL'
GROUP BY 1 ORDER BY 1 DESC;

Citations

[1] Stripe Webhook Event Mapping Reference

### 4. Incident Response Playbook (`/playbooks/churn_triage.md`)

```markdown
---
type: Playbook
title: Customer Churn Alert Triage
description: Standard operating procedure for investigating sudden increases in subscription cancellations.
tags: [on-call, operations]
timestamp: 2026-06-18T08:00:00Z
---

# Trigger
This playbook fires when hourly CANCEL event spikes exceed the standard 3-sigma threshold.

# Triage Steps

1. **Verify Telemetry Latency:**
   Compare event ingestion time against payload timestamp in [Subscription Events](/tables/subscription_events.md).

2. **Execute Diagnostic Analysis:**
   Run the SQL cancellation trends query from [Subscription Events Examples](/tables/subscription_events.md#examples).

3. **Cross-reference Dataset Metrics:**
   Check if affected cohorts concentrate in specific marketing channels via [Customer Behavior Dataset](/datasets/customer_behavior.md).

4. **Escalate:**
   If logs indicate API communication issues, escalate to the `#billing-eng` Slack channel.

Positioning & Trade-Offs

vs RAG (Retrieval-Augmented Generation)

RAG re-derives knowledge at query time from raw chunks of unstructured content. OKF stores curated, cross-linked, version-controlled concepts that agents read and update directly. Not mutually exclusive — OKF bundles can feed a RAG pipeline, but the bundle itself is the authoritative, navigable artifact. RAG misses structured relationships (mapping column customer_id directly to its parent table’s description); OKF provides the pre-structured map.

vs CLAUDE.md / AGENTS.md

CLAUDE.md and AGENTS.md are per-repository agent instruction files — they tell an agent how to behave in a specific codebase context. OKF is a knowledge corpus format — it captures what things are and how they relate. Complementary, not competing.

vs Data Catalogs (Alation, Collibra)

Enterprise catalogs are heavy databases running on proprietary APIs. OKF doesn’t replace these — it references them. A data catalog can generate an OKF bundle representation, check it into Git, and lightweight development agents can consume it easily.

vs Domain-Specific Schemas (Avro, Protobuf, OpenAPI)

OKF doesn’t replace these — it references them. An OKF concept for an API endpoint would link to the OpenAPI spec; it wouldn’t try to re-express it in markdown. OKF is the context layer, not the schema layer.

Honest Trade-Off Read

What OKF gets right:

• Zero friction: cat to read, git clone to ship, any text editor to author.
• One required field is the right call. Broad adoption of a minimal spec beats narrow adoption of a rich one.
• Treating knowledge as version-controlled source code inherits diffs, blame, PRs, and review without ceremony.
• The permissive consumer model avoids the fragility death-spiral that kills most interoperability specs.
• Decoupling producers from consumers is architecturally sound. Any framework can produce; any consumer can read.

Open design space (v0.1 is a starting point):

• Contradiction handling — Two OKF docs disagree on the same fact. No merge semantics defined yet.
• Trust and provenance — Human-authored vs. agent-generated content looks identical. No trust tier signals.
• Typed relationships — All cross-links are untyped. “Joins with” and “depends on” look the same to a graph consumer.
• Stale content — No staleness signals beyond timestamp. Operational discipline is a process problem, not a format problem.
• Access control — Permissions are filesystem / git permissions — nothing in the spec.
• Faceted search — Tags are free-form strings. No controlled vocabulary or centralized tag registry.

Quick Reference