Open Knowledge Format, explained
Updated 2026-06-13 / OKF v0.1
Portable knowledge bundles for humans and AI agents.
v0.1
format version covered by this guide
7
copy-ready examples
6
adjacent standards compared
Example first
See it in 30 seconds.
Switch between common project types and copy the shape of an OKF bundle.
The examples are intentionally plain: folders, frontmatter, Markdown, and links before platforms.
File tree
okf/
|-- index.md
|-- log.md
|-- metrics/monthly-recurring-revenue.md
|-- tables/subscriptions.md
`-- playbooks/revenue-review.md
concept file
markdown
---
type: Metric
title: Monthly Recurring Revenue
description: Recurring subscription revenue normalized to a monthly period.
resource: dashboard://revenue/mrr
tags: [revenue, saas, finance]
timestamp: 2026-06-13T00:00:00Z
---
# Calculation
MRR is the predictable recurring revenue generated by active subscriptions in the [subscriptions table](/tables/subscriptions.md).
Include active subscriptions with recurring billing. Exclude one-time setup fees, refunds, and usage-only charges unless normalized into a recurring plan.
# Examples
```sql
select sum(monthly_amount_usd) as mrr
from analytics.subscriptions
where status = 'active';
```
# Citations
[1] [Revenue dashboard](dashboard://revenue/mrr)
File tree
okf/
|-- index.md
|-- datasets/sales.md
|-- tables/orders.md
|-- tables/customers.md
`-- metrics/gross-revenue.md
concept file
markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-06-13T00:00:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique order identifier. |
| `customer_id` | STRING | Foreign key to [customers](/tables/customers.md). |
| `total_usd` | NUMERIC | Order total in US dollars. |
# Citations
[1] [BigQuery table](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
File tree
okf/
|-- index.md
|-- routes/api-users.md
|-- models/user.md
|-- policies/user-policy.md
`-- jobs/sync-stripe-customer.md
concept file
markdown
---
type: Laravel Model
title: User Model
description: Authenticated account model for customers and internal operators.
resource: repo://app/Models/User.php
tags: [laravel, model, authentication]
timestamp: 2026-06-13T00:00:00Z
---
# Responsibilities
The User model represents an authenticated account and owns customer-facing resources.
# Related concepts
Used by the [API users route](/routes/api-users.md) and protected by the [user policy](/policies/user-policy.md).
# Citations
[1] [Source file](repo://app/Models/User.php)
File tree
okf/
|-- index.md
|-- post-types/product.md
|-- taxonomies/product-category.md
|-- acf/product-fields.md
`-- templates/single-product.md
concept file
markdown
---
type: WordPress Post Type
title: Product
description: Custom post type used to manage product content.
resource: wp-admin/edit.php?post_type=product
tags: [wordpress, post-type, content]
timestamp: 2026-06-13T00:00:00Z
---
# Purpose
The Product post type stores product landing pages and related metadata.
# Related concepts
Rendered by the [single product template](/templates/single-product.md) and enriched by [product fields](/acf/product-fields.md).
File tree
okf/
|-- index.md
|-- endpoints/create-customer.md
|-- schemas/customer.md
`-- errors/rate-limit.md
concept file
markdown
---
type: API Endpoint
title: Create Customer
description: Creates a new customer record.
resource: https://api.example.com/customers
method: POST
path: /api/customers
tags: [api, customers]
timestamp: 2026-06-13T00:00:00Z
---
# Request
Accepts a customer payload shaped by the [Customer schema](/schemas/customer.md).
# Response
Returns the created customer object or a [rate limit error](/errors/rate-limit.md).
# Examples
```http
POST /api/customers
Content-Type: application/json
```
File tree
okf/
|-- index.md
|-- teams/support.md
|-- policies/refunds.md
|-- systems/billing.md
`-- playbooks/incident-response.md
concept file
markdown
---
type: Policy
title: Refund Policy
description: Rules support and billing teams use when evaluating customer refund requests.
resource: docs://policies/refunds
tags: [support, billing, policy]
timestamp: 2026-06-13T00:00:00Z
---
# Purpose
The refund policy defines when support can approve a refund, when billing review is required, and which cases must be escalated.
# Decision points
* Check whether the customer has an active subscription in the [billing system](/systems/billing.md).
* Escalate disputes, chargebacks, and unclear billing events through the [incident response playbook](/playbooks/incident-response.md).
# Citations
[1] [Refund policy source](docs://policies/refunds)
File tree
okf/
|-- index.md
|-- systems/billing.md
|-- tools/stripe.md
|-- playbooks/support-triage.md
`-- constraints/agent-safety-rules.md
concept file
markdown
---
type: Constraint
title: Agent Safety Rules
description: Operating boundaries an AI agent must follow before using tools or changing customer-facing systems.
resource: docs://agent-context/safety-rules
tags: [agent, safety, tools]
timestamp: 2026-06-13T00:00:00Z
---
# Rules
The agent must read relevant system, tool, metric, and playbook concepts before taking action.
Do not change billing data, refund customers, send external messages, or modify production settings unless a human explicitly approves the specific action.
# Related concepts
Read the [billing system](/systems/billing.md), [Stripe tool](/tools/stripe.md), and [support triage playbook](/playbooks/support-triage.md) before using operational tools.
What is OKF?
A small folder can carry enough context for people, tools, and agents to understand how knowledge fits together.
A minimal format for exchanging knowledge bundles.
A bundle is a directory of concept files; each concept has YAML frontmatter, a Markdown body, and links that make relationships traversable.
01
Knowledge bundle
The unit of distribution: a folder, repo, archive, or subdirectory containing related knowledge.
02
Concept files
One Markdown document per metric, table, API, playbook, process, system, or idea.
03
Frontmatter
Required `type`, plus recommended title, description, resource, tags, timestamp, and extension keys.
04
Links and citations
Markdown links express relationships. Citations point to the sources behind claims.
Why this matters for AI agents.
Agents need more than raw documents. They need self-describing context they can read, filter by type, traverse through links, and preserve across tools.
Context pipeline
Build on OKF
Do not just read about it.
Because OKF is just Markdown, YAML, folders, and links, builders can start with small tools before inventing platforms.
Bundle templates
TemplateCreate bundle folders, root indexes, concept files, and logs for common projects.
View templatesPrompt generator
PromptCopy an agent prompt that creates OKF bundles for apps, APIs, warehouses, and knowledge bases.
Copy promptExamples
Copy small OKF bundles that show frontmatter, links, logs, and concept files.
View examplesStart here.
A small OKF bundle can begin as a folder in a repo. Keep the first pass boring: choose concepts, add required frontmatter, link related files, and validate.
- 1Create an `okf/` folder in a repo or export directory.
- 2Add a root `index.md` so people and agents can scan the bundle.
- 3Add concept files with a required `type` field and useful descriptions.
- 4Use bundle-relative links like `/tables/orders.md` to express relationships.
- 5Add citations where claims depend on external sources, then validate.
Compare OKF with adjacent standards.
Compare
OKF vs RAG
OKF gives retrieval systems cleaner source context plus relationships; it does not replace retrieval.
Compare
OKF vs MCP
MCP connects agents to tools and systems; OKF packages knowledge and context.
Compare
OKF vs llms.txt
llms.txt can point at a site; OKF can map the concepts and relationships inside it.
Compare
OKF vs AGENTS.md
AGENTS.md guides coding agents inside a repo; OKF describes broader system knowledge.
Compare
OKF vs OpenAPI
OpenAPI describes APIs; OKF can describe broader context around APIs, data, metrics, and operations.
Compare
OKF vs data catalog
Data catalogs manage enterprise metadata; OKF is lightweight, file-based, portable, and Git-friendly.
Create a bundle, then validate it.
Start with a prompt or template, review the generated concept files, and use the validator before sharing the folder with people or agents.