# Open Knowledge Format > A minimal, interoperable format for knowledge representation in agentic AI systems — the missing context layer between raw data and agent reasoning. - **Category**: - **Canonical URL**: https://designpattern.fyi/okf/ --- ## Description A minimal, interoperable format for knowledge representation in agentic AI systems — the missing context layer between raw data and agent reasoning. ## Additional Notes **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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). **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 | Term | Definition | |---|---| | **Knowledge Bundle** | A self-contained directory tree of knowledge documents. The unit of distribution. | | **Concept** | A single unit of knowledge — one markdown file. Can be a table, an API, a metric, a runbook, an idea. | | **Concept ID** | The file path within the bundle, `.md` suffix stripped. e.g., `tables/users.md` → `tables/users` | | **Frontmatter** | YAML metadata block delimited by `---` at the top of the file. | | **Body** | Everything after the frontmatter — free-form markdown. | | **Link** | A standard markdown link between concepts — how the knowledge graph is built. | ### 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. ├── .md <- A concept at the root. └── / ├── index.md ├── .md └── / └── ... ``` **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:** ```yaml --- type: # REQUIRED — the only required field title: # Recommended description: # Recommended — used for index snippets and search resource: # 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:** | Heading | Purpose | |---|---| | `# Schema` | Structured field/column descriptions | | `# Examples` | Fenced code blocks showing usage | | `# Citations` | Numbered external sources backing claims | ### Cross-Linking Concepts link to each other via standard markdown links — this is how the knowledge graph is formed. **Absolute (bundle-relative) — preferred:** ```markdown See the [customers table](/tables/customers.md) for the join key. ``` **Relative:** ```markdown 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: ```markdown # 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: ```markdown # 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`) ```markdown --- 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`) ```markdown --- 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`) ```markdown --- 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](https://stripe.com/docs/api/events) ``` ### 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 | Thing | Rule | |---|---| | Only required frontmatter field | `type` | | Reserved filenames | `index.md`, `log.md` | | Preferred link form | Absolute bundle-relative (`/path/to/concept.md`) | | Conventional body headings | `# Schema`, `# Examples`, `# Citations` | | Conformance check | All `.md` files have frontmatter with non-empty `type` | | Consumer tolerance | Must not reject on unknown types, missing optional fields, broken links | | Version declaration | `okf_version: "0.1"` in root `index.md` frontmatter | | Date format | ISO 8601 (`YYYY-MM-DD` for log headings, datetime for `timestamp`) | | Distribution | Git repo (recommended), tarball, or subdirectory | | License | Apache 2.0 |