What Is the Open Knowledge Format (OKF)?
A Complete Guide for Developers

TL;DR — What Is OKF in One Sentence

Open Knowledge Format (OKF) is a vendor-neutral, filesystem-based standard for packaging knowledge as plain markdown files with YAML frontmatter — designed to be authored by humans, consumed by AI agents, and managed in version control.

Think of it as Markdown + structured metadata organized into portable directories (called "bundles") that encode concepts, instructions, schemas, and tool definitions. An AI agent can discover an OKF bundle, load it into context, and immediately understand a domain — without any SDK, API call, or proprietary format.

OKF was launched by Google Cloud Platform as part of their Knowledge Catalog initiative. It quickly gained traction across the AI agent ecosystem, with 239 bundles now indexed on BundleDex and growing daily.

What Is OKF? A Detailed Explanation

The Open Knowledge Format is a specification for representing knowledge as directory trees of markdown documents. Each document is a "concept" — a self-contained unit of knowledge with YAML frontmatter for metadata and a markdown body for content.

The Core Idea

Knowledge should be:

• Human-readable without tooling — open a file in any editor, or use cat in a terminal. No binary formats, no databases, no proprietary query languages.
• Agent-consumable without SDKs — an LLM's context window can ingest a markdown file directly. No parsing libraries needed.
• Version-controllable — bundles live in git (or any VCS). Pull requests, code review, diffs, and blame all work naturally.
• Portable — a bundle is a directory. Tar it, ship it, mount it, sync it. No lock-in, no vendor dependencies.
• Composable — bundles can link to each other, inherit concepts, and form rich knowledge graphs.

History and Origins

OKF emerged from the Google Cloud Platform Knowledge Catalog team, who recognized that the growing ecosystem of AI coding agents (Claude Code, Cursor, GitHub Copilot, OpenCode) needed a standardized way to discover and consume domain knowledge. Before OKF, every agent framework had its own ad-hoc approach — some used JSON files, others used custom YAML schemas, and most relied on API endpoints that changed between versions.

The OKF specification v0.1 was published as an open standard, welcoming contributions from the community. Since then, tools like OKFy (document conversion), the Open Knowledge CLI, and hundreds of community bundles have formed a thriving ecosystem.

How OKF Bundles Work

An OKF "bundle" is simply a directory of markdown files. The directory structure encodes relationships between concepts, and each file's YAML frontmatter provides machine-readable metadata.

Bundle Directory Structure

my-bundle/
├── index.md               # Bundle manifest (optional)
├── log.md                 # Changelog / update history (optional)
├── getting-started.md     # A concept document
├── api-reference.md       # Another concept document
├── guides/
│   ├── index.md           # Subdirectory listing
│   ├── installation.md    # Nested concept
│   └── configuration.md
└── examples/
    └── basic-usage.md

Concept Document Structure

Each concept document has two parts: YAML frontmatter (between --- delimiters) and a markdown body.

---
title: Getting Started with My API
description: A quick tutorial on using the MyAPI endpoints
tags: [api, tutorial, quickstart]
version: "1.0"
author: Example Corp
okf_version: "0.1"
---

## Overview

MyAPI is a RESTful service that provides [domain-specific functionality].

## Authentication

All API requests require an API key passed via the `X-API-Key` header.

## First Request

```bash
curl -H "X-API-Key: $API_KEY" https://api.example.com/v1/hello
```

## Next Steps

See the [API Reference](./api-reference.md) for full endpoint documentation.

Metadata Fields

The YAML frontmatter supports these standard fields:

Example Bundle Structure

Here's a real-world bundle structure from the iwe project (the most-starred OKF bundle with ★ 1,266 stars):

iwe/
├── index.md               # Bundle overview
├── log.md                 # Changelog
├── architecture.md        # System architecture
├── features.md            # Feature documentation
├── concepts/
│   ├── memory-graph.md    # Core concept: memory graph
│   ├── agent-sync.md      # Core concept: agent synchronization
│   └── markdown-memory.md # Core concept: markdown as memory
├── guides/
│   ├── getting-started.md
│   ├── configuration.md
│   └── advanced-usage.md
└── references/
    ├── api.md
    └── cli-commands.md

Each file is a self-contained concept document. The bundle's index.md serves as an entry point:

---
title: iwe — Markdown Memory System
description: A markdown memory system for you and your AI agent
tags: [memory, markdown, ai-agents, knowledge-graph]
version: "0.2.0"
author: iwe-org
okf_version: "0.1"
---

# iwe

**iwe** is a markdown-based memory system designed for both humans and AI agents.
It enables persistent, structured, and queryable memory that survives across sessions.

## Core Features

- **Markdown-native** — all memory is plain markdown, readable and writable by any tool
- **Agent-friendly** — AI agents can directly read and write memory files
- **Knowledge graph** — concepts link naturally via markdown links
|- **{{ bundles }}
- **Version-controlled** — memory is just files; git tracks everything

## Getting Started

See the [Getting Started Guide](./guides/getting-started.md).

Other top bundles you can explore:

• Lineage Skill (★ 267) — Claude Code skill for managing lineage and context
• echoes-vault-opencode (★ 143) — Vault for OpenCode agent knowledge
• Claude Mega Brain (★ 108) — Large-scale Claude Code knowledge base
• infra (★ 67) — Infrastructure knowledge bundle

How AI Agents Use OKF

OKF bundles are designed for the way AI coding agents work. Here's how the most popular agents consume OKF:

Claude Code

Claude Code (Anthropic's terminal-based AI agent) can load OKF bundles as part of its context. By pointing Claude Code to a bundle directory, the agent gains deep knowledge of a domain:

# Load an OKF bundle as context
claude /path/to/bundle/

# Claude Code Skills (OKF-format bundles)
claude ~/.claude/skills/my-skill/

Claude Code Skills are themselves OKF bundles placed in the ~/.claude/skills/ directory. The Lineage Skill and OKF Knowledge Skill are popular examples.

Cursor

Cursor's AI features can reference OKF bundles for domain-specific rules and context. The .cursorrules file can reference bundle directories, and Cursor's agent mode can search bundled knowledge inline.

OpenCode

OpenCode (by Nous Research) natively supports OKF bundles. Agents can discover bundles through BundleDex's API at /api/bundles.json, download them, and load them into workspace context. The echoes-vault-opencode bundle is purpose-built for OpenCode.

Generic AI Agent Integration

Any LLM-based agent can consume OKF bundles using this universal pattern:

# 1. Discover bundles via BundleDex API
curl https://bundledex.net/api/bundles.json

# 2. Clone a bundle repository
git clone https://github.com/owner/bundle.git

# 3. Read index.md to understand the bundle
cat bundle/index.md

# 4. Load concept docs into agent context
cat bundle/concepts/*.md

OKF vs MCP vs Function Calling

A common question is how OKF relates to other standards in the AI ecosystem. Here's a clear breakdown:

When They Work Together

OKF, MCP, and function calling are complementary, not competing:

• Use OKF bundles to give an agent deep domain knowledge before it starts working
• Use MCP servers to give the agent access to live tools and data during a session
• Use function calling for specific API-driven operations within the agent's runtime

For example, an agent might load an infrastructure OKF bundle to learn about your cloud architecture, then use an MCP server to query live cloud resources, and call functions to provision new instances.

How to Create Your First OKF Bundle

Creating an OKF bundle is straightforward. Follow these steps:

Step 1: Create a Directory

mkdir my-knowledge-bundle
cd my-knowledge-bundle

Step 2: Create an index.md

---
title: My Knowledge Bundle
description: A bundle of knowledge about [your topic]
tags: [knowledge, guide, okf]
version: "0.1.0"
author: Your Name
okf_version: "0.1"
---

# My Knowledge Bundle

This bundle contains knowledge about [your topic].

## Contents

- [Getting Started](./getting-started.md)
- [Core Concepts](./concepts/core.md)
- [Reference](./reference.md)

Step 3: Add Concept Documents

---
title: Getting Started
description: How to get started with this knowledge
tags: [tutorial]
---

## Getting Started

This is a concept document. Write in plain markdown.
Use `code blocks` for examples.

- Lists help organize information
- Cross-link to other concepts: see [Core Concepts](./concepts/core.md)

Step 4: Structure Subdirectories

mkdir concepts references
mv getting-started.md ./
touch concepts/core.md concepts/advanced.md
touch references/api.md

Step 5: Initialize Git and Publish

git init
git add -A
git commit -m "Initial OKF bundle"
git remote add origin https://github.com/your-username/my-knowledge-bundle.git
git push -u origin main

Step 6: Submit to BundleDex

Get your bundle indexed so AI agents can discover it:

1. Go to BundleDex Submit page
2. Enter your GitHub repository URL
3. Add a description and tags
4. We'll review and add it within 24 hours

Pro Tips

• Use descriptive tags — they power search and categorization. Good tags: okf, ai-agents, knowledge-base, mcp, cli
• Cross-link concepts — use relative markdown links to connect related ideas
• Keep concepts focused — each file should cover one topic well, not everything at once
• Use log.md to track bundle updates and version history
• Use OKFy to convert existing documentation into OKF format automatically

Why BundleDex Exists

As the OKF ecosystem grew, so did the problem of discovery. Bundles were scattered across thousands of GitHub repositories with no centralized index. AI agents had no standard way to find relevant knowledge bundles.

BundleDex solves this. We are the definitive directory of OKF bundles, currently indexing 239 bundles with 104 OKF-conformant entries.

What BundleDex Offers

• Agent-friendly API — /api/bundles.json returns the full index in JSON, consumable by any agent
• MCP Server — bundledex.net/mcp provides an MCP endpoint for agent-native discovery
• Search and filtering — find bundles by category, tag, stars, or conformance level
• Structured data — every page has JSON-LD for AI search engines
• Per-bundle badges — shields.io-style SVG badges for README inclusion
• Open submission — submit your bundle and get listed within 24 hours

For AI Agents

If you're building an agent that needs to discover OKF bundles, start here:

# Discover all bundles
curl https://bundledex.net/api/bundles.json

# Search for specific bundles (use our MCP endpoint)
# See bundledex.net/mcp for setup

# Get a specific bundle
curl https://bundledex.net/bundles/iwe/

BundleDex is and always will be free and open. It's built for the agent ecosystem, by the agent ecosystem.

FAQ