oriz.in / knowledge
type: service
status: active
timestamp: 2026-06-24
tags: [okf, standard, knowledge, google-cloud, format]

Open Knowledge Format (OKF)

Vendor-neutral spec for representing knowledge as Markdown + YAML frontmatter

Open Knowledge Format (OKF)

What It Is

OKF is an open, vendor-neutral specification published by Google Cloud on June 12, 2026 as version 0.1 (Draft). It formalizes Andrej Karpathy’s “LLM wiki” pattern (a Markdown knowledge base an agent reads and maintains like code) into a portable standard.

Design Principles

PrincipleMeaning
Just MarkdownReadable in any editor, renders on GitHub, indexable by any search tool
Just filesShippable as tarball, hostable in any git repo, mountable on any filesystem
Just YAML frontmatterMinimal structured fields; no schema registry, no SDK, no runtime

The Three Properties

PropertyDescription
Readable by humans without toolingAny text editor works
Parseable by agents without bespoke SDKscat a file to read it; git clone to ship it
Diffable in version controlPlain text + structured frontmatter = meaningful diffs
Portable across tools, organizations, and timeNo vendor lock-in

Problems OKF Solves

The Context-Assembly Problem

Before an AI agent can act, it must assemble context — schemas, metric definitions, runbooks, join paths — from scattered, incompatible sources:

OKF solves this by providing a lingua franca: a shared format any producer can write and any consumer can read, without translation.

The Stack OKF Fits Into

robots.txt / sitemap.xml  → tells crawlers which URLs exist
llms.txt                  → points agents at pages worth reading
AGENTS.md / CLAUDE.md     → tells coding agents how to behave
Open Knowledge Format     → hands agents the knowledge itself

Bundle Structure

An OKF bundle is a directory tree of Markdown files:

path/to/bundle/
├── index.md              # Optional. Directory listing (progressive disclosure)
├── log.md                # Optional. Chronological update history
├── <concept>.md          # A concept at bundle root
└── <subdirectory>/
    ├── index.md
    ├── <concept>.md
    └── ...

Reserved Filenames

FilenamePurpose
index.mdDirectory listing for progressive disclosure
log.mdChronological update history (ISO 8601 headings)

Hierarchy Depth

L1 file countMax depth
≤152 (knowledge/<L1>/<file>.md)
16–503 (knowledge/<L1>/<L2>/<file>.md)
51–1504
151+5 (absolute ceiling)

Concept Document Format

YAML Frontmatter

---
type: <Type name>                  # REQUIRED
title: <Display name>
description: <One-line summary>
resource: <Canonical URI>
tags: [<tag>, <tag>, …]
timestamp: <ISO 8601 datetime>
---
FieldRequiredPurpose
typeYESIdentifies the kind of concept. Unknown types tolerated.
titleRecommendedHuman-readable display name
descriptionRecommendedOne-line summary for retrieval
resourceRecommendedCanonical URI to the asset
tagsRecommendedCross-cutting categorization
timestampRecommendedLast-modified ISO 8601

Body

Standard Markdown. Favor structural elements (headings, lists, tables, fenced code blocks) over freeform prose.

Conventional section headings (SHOULD use when applicable):

HeadingPurpose
# SchemaStructured description of fields/columns
# ExamplesConcrete usage examples
# CitationsExternal sources backing claims

Cross-linking

Conformance (v0.1)

A bundle is conformant if:

  1. Every non-reserved .md file has parseable YAML frontmatter
  2. Every frontmatter has a non-empty type field
  3. Reserved filenames follow spec when present

Consumers MUST NOT reject bundles for missing optional fields, unknown types, extra keys, broken links, or missing index files.

Relationship to Other Standards

StandardRelationship to OKF
llms.txtPoints agents at pages to read. OKF goes deeper — hands over content.
AGENTS.md / CLAUDE.mdTell agents rules of behavior. OKF supplies the knowledge graph.
MCP (Model Context Protocol)Connection layer for tools at runtime. OKF is the curated knowledge layer. Complementary.
RAG (Retrieval-Augmented Generation)RAG retrieves chunks from large corpuses. OKF gives RAG cleaner structured source material. Complementary.
Schema.orgStructured data for search engines. OKF is for AI agent context, not SEO.

What Google Shipped with the Spec

Versioning

Adoption in This Family

This knowledge/ directory IS an OKF bundle. See:

Edit on GitHub · Back to index