Open Knowledge Format (OKF)

What is the Open Knowledge Format?

The Open Knowledge Format (OKF) is an open specification, published by Google Cloud on 12 June 2026, for packaging knowledge so that both people and AI agents can read it without special tooling. An OKF bundle is a directory of markdown files. Each file is a concept. Each concept has a YAML frontmatter block. Concepts link to each other with ordinary markdown links, which makes the bundle a traversable graph.

That is the entire format. No schema registry, no central authority, no mandatory SDK. You can cat a concept to read it and git clone a bundle to distribute it.

Why it exists

Agents need curated organizational knowledge, and every vendor was inventing an incompatible way to store it. OKF’s bet is the opposite of ambition: define the smallest set of conventions that make a knowledge corpus self-describing, then stop. The design goals are that knowledge should be readable by humans without tools, parseable by agents without an SDK, diffable in version control, and portable across tools and time.

If you use Obsidian, most of this will sound familiar. Bundle is roughly vault, concept is roughly note, frontmatter is the YAML at the top of a note, and a link is a link. The spec’s own section on related formats names hierarchical markdown tools as an ancestor pattern. The difference is that OKF is specified, so two tools can agree on what they are looking at.

The structure

my_bundle/
├── index.md            # optional, a directory listing
├── log.md              # optional, dated change history
├── concept.md          # a concept at the bundle root
└── subdirectory/
    ├── index.md
    └── another.md

index.md and log.md are reserved filenames. Every other .md file is a concept.

Frontmatter

---
type: Playbook          # REQUIRED, and the only required field
title: Incident response
description: One sentence summarizing the concept.
resource: https://example.com/the-thing-this-describes
tags: [oncall, incident]
timestamp: 2026-06-01T10:00:00Z
---

type is a free string. Producers choose their own values and consumers are required to tolerate ones they do not recognize. Everything else is recommended, not required, and producers may add any keys they like as long as consumers preserve them on round-trip.

Conformance

A bundle conforms to OKF v0.1 if every non-reserved .md file has parseable frontmatter, every frontmatter block has a non-empty type, and any reserved files that exist follow their documented structure.

Consumers must not reject a bundle for missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index.md files. The permissiveness is deliberate: bundles get refactored and partially generated by agents, so strict validation would break constantly.

What v0.2 added

Version 0.2 shipped on 26 July 2026 and added a recommended trust layer that answers three questions about a concept: where did this come from, how much should you trust it, and is it still current.

sources:
  - resource: https://example.com/spec
    id: some-spec
    last_modified: 2026-07-25
generated: { by: human:jane, at: 2026-07-31T12:00:00Z }
verified:
  - { by: process:ci-lint, at: 2026-07-31T12:05:00Z }
status: draft
stale_after: 2026-12-31

generated.by and verified.by use human:<id> or process:<id> prefixes, so a bundle records whether a person or a machine produced each concept. A deprecated status or an expired stale_after are trust signals, never validation errors.

What Engram does with OKF today

Engram is an OKF-aware consumer. Your vault is a directory of markdown files with frontmatter and links, which is the shape OKF describes, and Engram reads the v0.1 frontmatter fields natively rather than treating them as opaque text.

OKF field	What Engram does
type	Read and indexed. Filter searches by it, with type suggestions in the search UI.
title	Used as the note title.
description	Read and stored.
resource	Read and stored.
tags	Read and indexed, filterable.
timestamp (plus modified, updated)	Read as a real date. Range-queryable.
created (plus date)	Read as a real date. Range-queryable.

The spec only asks consumers to tolerate these fields. Engram indexes three of them, so type and both dates are search filters rather than decoration. They are indexed under encryption: type through an HMAC blind index, the dates as ordinary timestamp columns.

Links work in both directions of the ecosystem. Engram’s link parser handles OKF’s markdown form [label](target.md) and Obsidian’s [[wikilink]] form, so a bundle written for one reads correctly in the other.

What Engram does not do yet

We would rather you learn this here than discover it later.

• No bundle export. You cannot yet click a button and get an OKF tarball. This is the gap we most want to close, because it is what turns portability from a promise into a file you are holding.
• No v0.2 trust fields. sources, generated, verified, status, and stale_after are not read. Per the spec’s permissive rule they pass through harmlessly, but we do not act on them.
• No index.md or log.md handling. Those files sync like any other note; Engram does not treat them as directory listings or change history.
• No # Citations extraction.
• Link resolution is by filename, not by path. OKF defines a concept ID as the full path minus .md. Engram resolves a link target by its basename, the way Obsidian does, so /tables/orders.md and /metrics/orders.md resolve to the same note. Flat bundles are fine; deeply nested bundles with repeated filenames are not.

We do not claim OKF conformance. Conformance in this spec is a property of a bundle, not of a product, and we are a minor version behind. What is true today is narrower and more useful: Engram reads OKF v0.1 frontmatter natively and makes it searchable.

OKF is a vendor-neutral open specification. Compatibility is not endorsement, and nothing here implies Google has reviewed or approved Engram.

Why this matters if you use Engram

Your vault already has the shape a published standard describes. That is not a feature we shipped; it is a consequence of the decision to keep your notes as plain markdown files in a folder you own, made before OKF existed.

The practical payoff is that adding type: Meeting or type: Reference to your frontmatter is not Engram-specific metadata. It is a standard field, it makes your search filters work, and it stays meaningful if you take the folder somewhere else entirely.

Sources

1. OKF specification (v0.1)
2. Introducing the Open Knowledge Format, Google Cloud blog, 12 June 2026
3. okf.md, annotated guide including the v0.2 changes