# What is OKF?

**Open Knowledge Format (OKF)** is an open specification for storing an organization's "knowledge" as a
**directory of Markdown files with YAML frontmatter**, so that both humans and AI agents can write, read,
exchange, and use that knowledge — without needing any SDK, database, or specialized tooling.

> If you can `cat` a file, you can read OKF · If you can `git clone` a repo, you can share OKF

## Background

OKF v0.1 was released on **12 June 2026** by the Data Cloud team at **Google Cloud**
(Sam McVeety and Amir Hormati) as a way of turning the **"LLM-wiki pattern"** proposed by Andrej Karpathy
into a portable, vendor-neutral standard.

The core idea of LLM-wiki is: instead of having an LLM re-discover raw documents from scratch every time
a question is asked, let AI **progressively synthesize knowledge into organized, pre-linked Markdown pages**,
then load only the relevant pages directly into context.

## Core Components (see Part 3 for details)

| Term | Short definition |
|----|----------------|
| **Bundle** | A directory of all knowledge files — the unit of distribution |
| **Concept** | One unit of knowledge = one `.md` file (e.g. a table, a metric, a playbook) |
| **Concept ID** | The file's path within the bundle with `.md` stripped, e.g. `tables/orders.md` → `tables/orders` |
| **Frontmatter** | The YAML block at the top of a file (stores metadata such as `type`, `title`, `tags`) |
| **Link** | A Markdown link between concepts = builds relationships into a graph |

## Example: a single concept file

File `tables/orders.md`:

```markdown
---
type: BigQuery Table
title: Orders
description: One row per customer order
tags: [sales, orders]
timestamp: 2026-06-15T00:00:00Z
---

# Schema
| Column | Type | Description |
| :--- | :--- | :--- |
| order_id | STRING | Order identifier (unique) |
| customer_id | STRING | FK to [customers](customers.md) |

# Joins
Joined to [customers](customers.md) via `customer_id`
```

As you can see, this is plain Markdown that is immediately human-readable — just a small YAML header and links to other concepts.

## 3 Design Principles

1. **Minimally opinionated** — frontmatter requires only a single `type` field; everything else is defined by the producer.
2. **Producer and consumer are independently decoupled** — a bundle written by hand, generated by an agent, or exported by a pipeline can be read by any tool.
3. **A graph, not just a tree** — concepts link to each other via Markdown links, creating richer relationships than folder structure alone.

## What OKF is NOT

- Not a fixed taxonomy — it does not prescribe which types must exist.
- Not an opinion on how knowledge must be stored, served, or searched.
- Not a replacement for domain-specific schemas (Avro, Protobuf, OpenAPI) — OKF **references** those; it does not absorb them.

Next, let's look at **why** you would choose OKF over traditional RAG → [Why OKF?](./why-okf.md)
