OKF vs Obsidian:
What's the Difference?

Quick Overview

If you're involved in knowledge management — whether for yourself, your team, or AI agents — you've likely encountered two things: Obsidian, the wildly popular personal knowledge management (PKM) tool, and OKF (Open Knowledge Format), the emerging standard for packaging structured knowledge for AI agent consumption.

Below, we break down both, explore how they relate, and show you how to use them together for maximum effectiveness — whether you're managing your personal knowledge or preparing content for the AI agent ecosystem.

What Is Obsidian?

Obsidian is a powerful personal knowledge management application built on a foundation of local markdown files. It's designed for creating, linking, and exploring your notes — whether you're a researcher, writer, developer, or lifelong learner.

How Obsidian Works

Obsidian operates on a simple but powerful concept: your notes are plain markdown files stored in a local folder called a vault. Everything in Obsidian revolves around this vault:

my-obsidian-vault/
├── .obsidian/           # Obsidian config (themes, plugins, settings)
├── Projects/
│   ├── Project Alpha.md
│   └── Project Beta.md
├── Notes/
│   ├── Meeting Notes 2026-07-12.md
│   └── Book Notes - Atomic Habits.md
├── Daily Notes/
│   ├── 2026-07-10.md
│   └── 2026-07-11.md
├── Templates/
│   └── daily-note-template.md
└── index.md

Key Features of Obsidian

• Local-first — your notes live on your machine as plain markdown files. No cloud lock-in, no proprietary format
• Wikilinks and backlinks — link notes using [[wikilinks]] and see which notes reference each other in the backlinks pane
• Graph view — visualize connections between your notes as an interactive graph of nodes and edges
• Plugin ecosystem — hundreds of community plugins extend Obsidian with calendars, Kanban boards, databases, and more
• YAML frontmatter — every note can have structured metadata (tags, dates, aliases) in its frontmatter
• Templates — create reusable templates for consistent note structure
• Canvas — a visual workspace for arranging and connecting ideas spatially

Obsidian's strength is its flexibility. It's not a rigid system — you organize your vault however makes sense to you. This makes it a powerful tool for thought, research, and project management.

What Is OKF (Open Knowledge Format)?

OKF (Open Knowledge Format) is a directory-based standard for packaging structured knowledge as markdown files. Launched by Google Cloud Platform in mid-2026, it's designed for AI agents to consume directly — without needing to browse or fetch additional pages.

How OKF Works

my-knowledge-bundle/
├── index.md         # Bundle manifest with YAML frontmatter
├── log.md           # Changelog
├── concepts/
│   ├── setup.md     # Concept document with metadata
│   └── architecture.md
├── guides/
│   ├── getting-started.md
│   └── configuration.md
└── references/
    └── api.md

Key Characteristics of OKF

• Directory structure — knowledge is organized in a hierarchy of markdown files under a root directory
• YAML frontmatter — every file has structured metadata (title, description, tags, version, author)
• Agent-first — designed for AI agents to load and traverse directly as context
• Cross-linked — concepts link to each other, forming a knowledge graph that agents can navigate
• Version-controlled — bundles live in git repositories, with full history and collaboration via pull requests
• Portable — a bundle is a directory of markdown files; it works anywhere, on any platform
• Discoverable — bundles are indexed on BundleDex, the definitive directory of OKF bundles

OKF is ideal for packaging domain knowledge that an AI agent needs to understand before working with a tool, library, API, or concept. It's the format behind BundleDex, the directory that makes OKF bundles discoverable and searchable.

How OKF Relates to Obsidian

At first glance, OKF and Obsidian might seem like they serve different worlds — one for AI agents, one for humans. But they share a surprising amount of DNA:

Shared Foundations

Both OKF and Obsidian are built on plain markdown files with YAML frontmatter. This means:

• Any OKF bundle is a valid Obsidian vault (just open the directory)
• Any Obsidian vault can be structured as an OKF bundle (with some reorganization)
• Obsidian's backlinks and graph view work naturally with OKF's cross-linked structure
• YAML frontmatter used in OKF (title, description, tags) maps directly to Obsidian's frontmatter fields

Different Purposes

Despite the shared format, OKF and Obsidian serve different purposes:

• Obsidian is a tool for creation — it's for writing, linking, exploring, and thinking. It's personal, interactive, and designed for the human cognitive process.
• OKF is a format for distribution — it's for packaging knowledge so that AI agents can consume it. It's standardized, portable, and designed for machine readability.

Think of it this way: you use Obsidian to write your knowledge, and you use OKF to publish it for AI agents. They're not competing — they're different stages of the same knowledge lifecycle.

Can Obsidian Vaults Be OKF Bundles?

This is the most common question when comparing OKF and Obsidian, and the answer is: partially, with some important caveats.

What Works

An Obsidian vault can be structured to look like an OKF bundle. The basic building blocks are the same:

• Markdown files — both use the same file format
• YAML frontmatter — both use frontmatter for metadata
• Internal links — both use links between files (though the syntax differs: [[wikilink]] vs [markdown link](file.md))
• Directory organization — both organize files into a folder hierarchy

What Doesn't Work

There are several reasons a typical Obsidian vault does not qualify as an OKF bundle:

• No index.md manifest — OKF requires a bundle manifest at the root with specific metadata fields. Most Obsidian vaults don't have this.
• Obsidian-specific files — the .obsidian/ directory contains configuration, cache, and plugin data that aren't part of OKF and would confuse an agent consuming the bundle.
• Plugin-dependent content — Obsidian plugins like Dataview, Kanban, and Excalidraw create content that won't render properly in a plain markdown reader.
• Wikilinks vs markdown links — Obsidian's [[wikilinks]] are not standard markdown. OKF uses standard markdown links for maximum compatibility.
• Personal vs. publishable — most vaults contain personal notes, drafts, and ephemera that aren't suitable for public distribution.

The Bottom Line

You can structure a vault to be OKF-compatible, but your typical Obsidian vault won't be a valid OKF bundle out of the box. If you want to publish your vault's content as an OKF bundle, you'll need to:

1. Create an index.md manifest file with proper OKF metadata
2. Remove the .obsidian/ directory (or exclude it from the bundle)
3. Convert [[wikilinks]] to standard markdown links
4. Strip out plugin-specific content and personal notes
5. Organize files into the standard OKF directory structure

Tools and scripts to automate this conversion are emerging in the OKF ecosystem. Check BundleDex for updates on vault-to-bundle tooling.

How to Use OKF Bundles in Obsidian

While converting a vault to an OKF bundle takes some work, using OKF bundles in Obsidian is straightforward. Here's how:

Method 1: Open a Bundle as a Vault

Since OKF bundles are directories of markdown files, you can open any bundle as an Obsidian vault:

1. Clone or download an OKF bundle from BundleDex or its source repository
2. In Obsidian, click Open folder as vault and select the bundle directory
3. Obsidian will load all files, parse the YAML frontmatter, and build the graph view
4. You can now browse, search, and explore the bundle's knowledge using Obsidian's tools

This is incredibly useful for studying a bundle's content. Instead of navigating a flat directory, you get Obsidian's graph view, backlinks, and search — all working with the bundle's cross-linked structure.

Method 2: Import Bundle Files into Your Vault

If you want to incorporate OKF knowledge into your existing vault:

1. Download the bundle's files to a subdirectory in your vault (e.g., vault/Knowledge Bundles/OKF Bundle Name/)
2. Obsidian will index the files and add them to your graph automatically
3. Create links from your existing notes to the bundle's content
4. Use the bundle's YAML frontmatter for searching and filtering

Method 3: Author OKF Bundles in Obsidian

Obsidian is an excellent editor for creating OKF bundles. Here's a workflow:

1. Create a new vault for your bundle (or use a dedicated folder)
2. Set up the OKF directory structure: concepts/, guides/, references/
3. Create an index.md with the required OKF frontmatter
4. Write your content using Obsidian's editor — use markdown links ([text](file.md)) instead of wikilinks
5. Use Obsidian's graph view to verify your cross-linking is coherent
6. Export the vault (excluding .obsidian/) as your OKF bundle

Recommended Plugins for OKF Work in Obsidian

• Templater — create dynamic templates that auto-generate OKF frontmatter fields
• Frontmatter Title — display the YAML title as the note's displayed name
• Metadata Menu — manage frontmatter fields with a spreadsheet-like interface
• Tag Wrangler — bulk-rename and organize tags across your bundle
• Linter — auto-format markdown and frontmatter to match OKF conventions

Side-by-Side Comparison

When to Use Each

Use Obsidian When...

• You're taking personal notes, doing research, or building a second brain
• You need a rich editing experience with plugins, templates, and graph visualization
• Your notes are private or in-progress — not ready for public distribution
• You want to explore connections between ideas using backlinks and graph view
• You're writing drafts, thinking through problems, or organizing project knowledge

Use OKF When...

• You want to publish knowledge for AI agents to consume
• You have domain expertise that agents need to understand (libraries, APIs, tools, concepts)
• You want your knowledge indexed and discoverable on BundleDex
• You need a portable, version-controlled format for sharing knowledge across teams and systems
• You're building developer tools, SDKs, or documentation that should be agent-friendly

Use Both When...

• You want to author OKF bundles using Obsidian's editing experience
• You have a vault with publishable knowledge that you want to prepare for AI agents
• You want to study OKF bundles interactively using Obsidian's graph view and search
• You're building a workflow that moves from personal knowledge (Obsidian) to published knowledge (OKF)

Recommended Workflow: From Obsidian to OKF

Here's a practical workflow for moving from personal knowledge in Obsidian to published OKF bundles on BundleDex:

Step 1: Create in Obsidian

Use Obsidian as your primary writing environment. Take advantage of its features:

• Write freely using wikilinks, tags, and YAML frontmatter
• Use the graph view to ensure your knowledge is well-connected
• Leverage templates for consistent note structure
• Keep personal notes and publishable content in separate folders

Step 2: Curate for Publishing

Identify the sections of your vault that are suitable for public distribution:

• Extract content that represents established, well-structured knowledge
• Remove personal reflections, work-in-progress, and sensitive information
• Fact-check and review for accuracy — OKF bundles are authoritative references
• Add structured metadata: version numbers, author credits, and clear descriptions

Step 3: Convert to OKF Structure

Restructure the curated content into an OKF bundle:

# From Obsidian vault structure:
my-vault/
├── .obsidian/
├── Concepts/
│   ├── What is OKF.md
│   └── How Bundles Work.md
├── Guides/
│   └── Getting Started.md
└── Personal Notes/
    └── Ideas.md

# To OKF bundle structure:
my-bundle/
├── index.md           # Bundle manifest
├── log.md             # Changelog
├── concepts/
│   ├── what-is-okf.md
│   └── how-bundles-work.md
├── guides/
│   └── getting-started.md
└── references/
    └── glossary.md

Step 4: Convert Links

Replace Obsidian wikilinks with standard markdown links:

# Obsidian wikilink syntax:
See [[What is OKF]] for details.

# OKF markdown link syntax:
See [What is OKF](concepts/what-is-okf.md) for details.

Step 5: Add Bundle Manifest

Create an index.md at the bundle root with the required OKF frontmatter:

---
title: My Knowledge Bundle
description: A comprehensive guide to my domain expertise
version: 1.0.0
author: Your Name
tags: [knowledge, reference, guide]
license: CC-BY-4.0
---

# My Knowledge Bundle

This bundle contains structured knowledge about [topic].

## Contents

- [Concepts](concepts/) — Core concepts and definitions
- [Guides](guides/) — Step-by-step tutorials
- [References](references/) — API docs and reference material

Step 6: Publish to BundleDex

Once your bundle is ready, submit it to BundleDex for indexing. This makes it discoverable by AI agents and other knowledge seekers. BundleDex will validate your bundle structure and metadata, then add it to the directory.

FAQ