okf

A pure-Rust implementation, library and CLI toolkit for the Open Knowledge Format (OKF) v0.2: Google's open, human- and agent-friendly format for representing knowledge as a directory of Markdown files with YAML frontmatter.

What is OKF?

The Open Knowledge Format (OKF) is a specification from Google for representing written knowledge as a directory of Markdown files with structured YAML frontmatter.

An OKF bundle is plain text in a folder. There is no database, no external service, and no schema registry. If you can read a text file, you can read OKF.

Concepts: Individual Markdown documents (.md), each containing one piece of knowledge with YAML frontmatter.
Bundles: A directory tree of related concepts. An index.md file acts as the directory listing, and log.md records revision history.
Trust & verification: Frontmatter tracks who authored a concept (generated: { by, at }) and who or what verified it (verified: [{ by, at }]). Trust tiers (unverified, machine-confirmed, human-reviewed) are derived dynamically from these events.
Freshness & lifecycle: Concepts define status (draft, stable, deprecated) and explicit expiration dates (stale_after).
Provenance: Sources list where knowledge originated, who wrote it, and when it changed, with footnote citations linking claims directly to source IDs.
Attested computations: Executable contracts specifying parameters, runtimes (SQL, Python, dbt), execution receipts, and deterministic verification attesters.

The okf crate is a pure-Rust implementation, validator, linter, and CLI toolkit for working with OKF v0.2 bundles.

Hands-on quickstart (60 seconds)

1. Install the CLI

Install okf from crates.io:

cargo install okf

(Or install as a Cargo plugin via cargo install cargo-okf, which lets you run cargo okf <command>)

2. Initialize a new bundle

Create an OKF bundle with a root index.md, audit log.md, and an initial concept:

okf init company_knowledge --title "Company policies and operations"
cd company_knowledge

3. Create concepts

Scaffold new concepts with standardized frontmatter:

# Create a policy concept
okf new policies/travel_expenses --type Policy --title "Travel and expense policy" --description "Rules and reimbursement rates for business travel."

# Create an Attested Computation contract
okf new computations/mileage_calc --attested --title "Mileage reimbursement calculator"

4. Check conformance and auto-fix issues

Run validate and lint to audit your bundle:

# Validate strict OKF v0.2 conformance
okf validate .

# Run opinionated hygiene checks and automatically remediate fixable issues
okf lint . --fix

5. Inspect trust and visualize the graph

# View trust tiers and staleness status
okf trust .

# Generate a Mermaid graph of concept relationships (renders directly in GitHub Markdown)
okf graph . --format mermaid

6. Explore with OKF Studio

okf studio .

Interactive studio: okf studio

okf studio is an interactive terminal interface for exploring and managing OKF bundles.

Unlike one-off commands that run once and exit, the studio stays open and automatically updates when files are edited on disk.

Browse and read: Navigate directories, read rendered Markdown, follow links, and inspect metadata and revision history.
Visual link graph: Explore connections and dependencies between concepts interactively.
Audit bundle health: View trust levels, freshness, and concepts that need attention.
Computations: Inspect Attested Computation contracts and test parameter inputs.
Refactor safely: Move, rename, merge, split, or delete concepts with preview confirmation before changes are saved.

okf studio [bundle]

Anatomy of an OKF bundle

Directory structure

A typical OKF bundle repository looks like this:

company_knowledge/
├── index.md                      # Root table of contents (declares okf_version: "0.2")
├── log.md                        # Audit log of changes grouped by ISO-8601 date
├── policies/
│   ├── index.md                  # Subdirectory index (auto-generated)
│   ├── travel_expenses.md        # Concept document (Policy)
│   └── paid_time_off.md          # Concept document (Policy)
├── computations/
│   ├── index.md                  # Subdirectory index (auto-generated)
│   └── mileage_calc.md           # Attested Computation concept
└── references/
    ├── skills/submit_expense.md  # Execution instructions
    └── attesters/verify_rate.py  # Deterministic verifier

Concept document example

policies/travel_expenses.md:

---
type: Policy
title: Travel and expense policy
description: Rules and standard per-mile reimbursement rates for employee travel.
tags: [hr, finance, travel, expenses]
status: stable
generated:
  by: reference_agent/gemini-3.7-flash
  at: 2026-06-20T22:53:05Z
verified:
  by: human:sarah_hr
  at: 2026-06-25T09:00:00Z
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: mileage-guide
    resource: https://example.com/finance/mileage-guide
    title: Standard mileage reimbursement guidelines
---

# Travel and expense policy

Employees traveling on company business are reimbursed for personal vehicle usage at standard approved rates.[^mileage-guide]

Total reimbursement is calculated using the [Mileage reimbursement calculator](../computations/mileage_calc.md).

[^mileage-guide]: Standard mileage reimbursement guidelines

Attested computation example

computations/mileage_calc.md:

---
type: Attested Computation
title: Mileage reimbursement calculator
description: Sanctioned computation to calculate employee vehicle travel reimbursement.
status: stable
runtime: python
parameters:
  - { name: miles, type: number, required: true }
  - { name: rate_per_mile, type: number, required: false }
executor:
  resource: references/skills/submit_expense.md
  receipt: [report_id, calculated_amount, status]
attester:
  resource: references/attesters/verify_rate.py
generated:
  by: human:alex_finance
  at: 2026-06-15T10:00:00Z
verified:
  by: process:ci-nightly
  at: 2026-06-20T00:00:00Z
---

# Mileage reimbursement calculator

# Computation

```python
def calculate_reimbursement(miles: float, rate_per_mile: float = 0.67) -> float:
    return round(miles * rate_per_mile, 2)
```

Core concepts

Trust tiers

In a corpus where both humans and AI agents write documents, trust is critical. OKF derives trust tiers dynamically from verification events rather than storing a subjective score:

Trust tier	Meaning	Verification condition
`human-reviewed`	Highest confidence. Verified by a human.	At least one `verified.by` starts with `human:` (e.g., `human:alice`).
`machine-confirmed`	Moderate confidence. Checked by automated process or test suite.	Verified by a process (e.g., `process:nightly-ci` or `agent/v1`), with no human review.
`unverified`	Baseline draft or unreviewed agent output.	No `verified` entries present.

Freshness and staleness

Knowledge decays over time. The stale_after: YYYY-MM-DD field gives documents an explicit expiration date.

okf trust . flags stale concepts in terminal output.
okf validate . --today 2026-07-01 allows pinning a date in CI for deterministic staleness checks.

Provenance and footnote attribution

OKF documents record origin and credibility signals under sources:

sources:
  - id: mileage-guide
    resource: https://example.com/finance/mileage-guide
    title: Standard Mileage Reimbursement Guidelines
    author: human:finance_team
    last_modified: 2026-04-01T00:00:00Z
    usage_count: 1200

Inline claims reference sources via standard Markdown footnotes keyed to sources[].id (e.g., According to company guidelines...[^mileage-guide]).

Attested computations

An Attested Computation defines a contract for executing deterministic calculations:

runtime: Environment (e.g., python, bigquery, dbt, snowflake).
parameters: Typed arguments required for execution.
# Computation: The code or query (inline or referenced).
executor: Resource that executes the logic and returns a receipt.
attester: Deterministic script that verifies the receipt output.

Note: okf parses and validates attestation contracts; executing computation and attestation is a consumer-side runtime responsibility.

CLI reference and workflows

okf <command> [options] [arguments]

Interactive studio: studio

Open the interactive terminal UI:

# Open the current directory in studio
okf studio

# Open a specific bundle and start on the graph tab
okf studio ./company_knowledge --tab graph

# Check staleness against a pinned date and set an author identity
okf studio ./company_knowledge --today 2026-12-01 --author "human:sarah"

Scaffolding: init and new

# Initialize a new bundle in the current directory
okf init . --title "Company policies"

# Initialize a bare bundle without sample concept
okf init ./company_knowledge --bare

# Create a new concept with title and description
okf new policies/travel_expenses --type Policy --title "Travel and expense policy" --description "Rules and reimbursement rates for business travel"

# Create an Attested Computation concept
okf new computations/mileage_calc --attested --title "Mileage reimbursement calculator"

Bundle manipulation: mv, rm, split, and merge

Manipulating and refactoring a bundle without breaking cross-links is a first-class capability in okf:

# Move or rename a concept (rewrites all backlinks across the bundle + rebases outgoing links and anchors)
okf mv auth/token security/jwt --bundle ./company_knowledge

# Preview rename without writing to disk
okf mv auth/token security/jwt --dry-run --json

# Rename a section/heading in-place and rewrite all internal and bundle-wide anchor links
okf mv billing/pricing#pricing-tiers billing/pricing#subscription-plans

# Safely remove a concept (fails if incoming links point to it)
okf rm legacy/old_policy

# Re-route all backlinks pointing to the removed concept to a replacement
okf rm legacy/old_policy --redirect-to policies/new_policy

# Unlink backlinks into plain text
okf rm legacy/old_policy --unlink

# Extract a section/heading into a new concept document
okf split billing/pricing billing/enterprise --section "Enterprise Tier" --title "Enterprise Pricing"

# Consolidate two concepts into one (merges sources, footnotes, verified events, and backlinks)
okf merge billing/discounts billing/pricing

Quality gate: validate and lint

okf validate verifies strict OKF v0.2 specification conformance, checking schema validity, broken cross-links, missing attestation resources, and broken section anchors (exits with non-zero code on errors):

# Conformance check
okf validate ./company_knowledge

# Check conformance against a specific evaluation date
okf validate ./company_knowledge --today 2026-12-01

# Automatically fix conformant issues (e.g., migrate legacy v0.1 fields)
okf validate ./company_knowledge --fix

okf lint evaluates 13 opinionated hygiene rules (missing headings, orphan concepts, key ordering, heading hierarchy, whitespace issues):

# Lint bundle
okf lint ./company_knowledge

# Automatically apply fixes across all files (adds titles, headings, formats keys, fixes whitespace)
okf lint ./company_knowledge --fix

Auditing trust: trust and info

# View per-concept trust tier, verification history, and staleness
okf trust ./company_knowledge

Example Output:

policies/travel_expenses [stable] human-reviewed
  generated: reference_agent/gemini-3.7-flash at 2026-06-20T22:53:05Z
  verified:  human:sarah_hr at 2026-06-25T09:00:00Z
  stale_after: 2026-12-31
  source:    [mileage-guide] Standard mileage reimbursement guidelines
computations/mileage_calc [stable] machine-confirmed
  generated: human:alex_finance at 2026-06-15T10:00:00Z
  verified:  process:ci-nightly at 2026-06-20T00:00:00Z

2 concept(s):
     1  human-reviewed
     1  machine-confirmed

# Summarize bundle statistics, types, and health
okf info ./company_knowledge

Link graph and discovery: links and graph

# Inspect all internal and broken cross-links
okf links ./company_knowledge

# Check only for broken links (fails in CI if broken links exist)
okf links ./company_knowledge --broken --check

# Export cross-links in JSON format
okf links ./company_knowledge --format json

# Render link graph as Mermaid (ideal for GitHub READMEs or PR summaries)
okf graph ./company_knowledge --format mermaid --sources

# Export full dependency graph as JSON
okf graph ./company_knowledge --format json

Listing computations: computations

Inspect and list all Attested Computation contracts declared in the bundle:

# List all attested computation contracts
okf computations ./company_knowledge

Semantic diffs: diff

Perform semantic comparison between two OKF bundles (or two git worktrees):

okf diff ./bundle_v1 ./bundle_v2

Example Output:

added (1):
  + policies/paid_time_off
removed (0):
renamed (1):
  ~ policies/old_travel -> policies/travel_expenses
content (1):
  ~ policies/travel_expenses (body)
trust (1):
  policies/travel_expenses: tier unverified -> human-reviewed
added links (1):
  + policies/travel_expenses -> computations/mileage_calc

Formatting and indexing: fmt, index, and parse

# Dry-run format check for CI (exits with non-zero code if files need formatting)
okf fmt ./company_knowledge --check

# Format frontmatter and body in place across all markdown files
okf fmt ./company_knowledge -w

# Regenerate all index.md table-of-contents files across the directory tree
okf index ./company_knowledge

# Inspect AST and parsed frontmatter structure of a single document
okf parse ./company_knowledge/policies/travel_expenses.md

Universal JSON output: `--json` / `-j`

Every CLI subcommand supports machine-readable JSON output via --json (or -j / --format json) for automated pipelines and AI agent tool calling:

okf validate ./company_knowledge --json
okf lint ./company_knowledge --json
okf info ./company_knowledge --json
okf trust ./company_knowledge --json
okf fmt ./company_knowledge --check --json
okf diff ./bundle_v1 ./bundle_v2 --json

CI/CD integration

Add okf to your GitHub Actions workflow to automatically check every pull request:

.github/workflows/okf.yml:

name: Bundle CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    name: Conformance and lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Install okf
        run: cargo install okf

      - name: Check formatting
        run: okf fmt ./company_knowledge --check

      - name: Validate OKF conformance
        run: okf validate ./company_knowledge

      - name: Check broken links
        run: okf links ./company_knowledge --broken --check

      - name: Lint bundle
        run: okf lint ./company_knowledge

Using as a Rust library

Add okf or okf-core to your Cargo.toml:

cargo add okf

1. Loading and validating a bundle

use okf::{Bundle, ConceptId, Date, TrustTier, validate_bundle};

// Load bundle from disk
let bundle = Bundle::load("./company_knowledge")?;
println!("Loaded {} concepts", bundle.len());

// Conformance check
let report = validate_bundle(&bundle);
if report.is_conformant() {
    println!("Conformant with OKF v{}", okf::OKF_VERSION);
}

// Traverse cross-links and backlinks
let policy_id = ConceptId::parse("policies/travel_expenses")?;
for link in bundle.links_from(&policy_id) {
    println!("{} -> {} (exists: {})", policy_id, link.target, link.exists);
}
for backlink in bundle.backlinks(&policy_id) {
    println!("Referenced by backlink: {backlink}");
}

// Check trust and staleness
let today = Date::today_utc().unwrap();
for concept in bundle.concepts() {
    if concept.trust_tier() < TrustTier::HumanReviewed && concept.is_stale_on(today) {
        println!("Warning: {} is stale or unreviewed", concept.id);
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

2. Inspecting attested computations

use okf::Document;

let doc = Document::parse(
    "---\n\
     type: Attested Computation\n\
     runtime: python\n\
     parameters:\n\
     \x20 - { name: miles, type: number, required: true }\n\
     executor:\n\
     \x20 resource: references/skills/submit_expense.md\n\
     \x20 receipt: [report_id, calculated_amount, status]\n\
     ---\n\n# Computation\n\n\
     \x20   def calculate_reimbursement(miles: float, rate_per_mile: float = 0.67) -> float:\n\
     \x20       return round(miles * rate_per_mile, 2)\n",
)?;

let contract = doc.attested_computation().unwrap();
assert_eq!(contract.runtime.as_deref(), Some("python"));
assert_eq!(contract.required_parameters().count(), 1);
assert!(contract.computation.code().unwrap().contains("calculate_reimbursement"));
# Ok::<(), okf::DocumentError>(())

3. Multi-language syntax checking

use okf::{Bundle, check_syntax, lint_bundle};

let bundle = Bundle::load("./company_knowledge")?;
let report = lint_bundle(&bundle);

for diagnostic in report.diagnostics {
    println!("{diagnostic}");
}

// Check syntax directly for any supported language
assert!(check_syntax("python", "def calculate(total):
    return total * 0.2
").is_ok());
assert!(check_syntax("typescript", "const add = (a: number, b: number): number => a + b;").is_ok());
# Ok::<(), Box<dyn std::error::Error>>(())

Workspace crates

This repository is structured as a multi-crate Rust workspace:

Crate	Description	Documentation
`okf`	CLI binary and re-exports of all core and validator APIs.
`okf-core`	Pure-Rust OKF engine (YAML subset parser, AST, link graphs, diff, fix engine).
`okf-validator`	Conformance validator, multi-language syntax checker, and 13 opinionated linting rules.
`okf-studio`	The `okf studio` interactive terminal UI: explorer, graph, mission control, computations playground, and live refactoring.
`cargo-okf`	Cargo plugin wrapper allowing `cargo okf <cmd>`.

Design choices

Full frontmatter preservation: Rather than deserializing into rigid structs (which would drop custom or extension keys), Frontmatter maintains an order-preserving map and layers typed accessors on top. Unknown keys survive round-trips untouched.
Computed, not stored, trust signals: Trust tiers and credibility signals are derived at query time from verified actors. Storing a subjective trust number is fragile and non-portable.
Permissive and resilient loading: Bundle::load never crashes on a single broken file; parse errors and broken links are collected as diagnostic graph items so you can inspect and fix them.
Deterministic by default: Staleness checks are opt-in (--today) so validation remains reproducible across different execution environments.

Mapping to the spec

Spec section	Responsibility	Module
§2 Terminology / Concept ID	Identifier normalization & path resolution	`concept_id::ConceptId`
§3 Bundle structure	Directory traversal & reserved files	`bundle::Bundle`
§4 Concept documents	Document AST, YAML frontmatter, body	`document::Document`, `frontmatter::Frontmatter`
§5.1 Provenance	Sources, credibility signals, footnotes	`provenance::Source`, `provenance::attributions`
§5.2 Trust	`generated`, `verified` actors & timestamps	`trust::Generated`, `trust::Verification`
§5.3 Trust tiers	`unverified`, `machine-confirmed`, `human-reviewed`	`trust::TrustTier`
§5.4 / §5.5 Lifecycle	`status: draft\|stable\|deprecated`, `stale_after`	`trust::Status`, `trust::is_stale_on`
§6 Cross-linking and paths	Relative link parsing, targets, and backlinks	`links`
§7 Actor convention	`human:<id>`, `process:<id>`, `<producer>/<ver>`	`actor::Actor`
§8 Index files	Auto-generation of directory `index.md` listings	`index::regenerate_indexes`
§9 Log files	Parsing and formatting `log.md` histories	`log::Log`
§10 Attested computations	Contract models, parameters, and inline/external script syntax validation	`computation::AttestedComputation`, `syntax::check_syntax`
§11 Conformance	Conformance testing engine & diagnostic reporting	`validate::validate_bundle`

License

Licensed under the Apache License, Version 2.0, matching the upstream Open Knowledge Format project. See LICENSE and NOTICE for details.

Disclaimer: This is an independent open-source implementation and is not affiliated with or endorsed by Google.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
crates		crates
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

okf

Table of Contents