Getting your vault OKF-ready

The Open Knowledge Format is a plain folder of markdown that agents can read without an SDK. A typed vault is already most of the way there. This article covers the four habits that close the gap, the export command that does the rest without losing your typed edges, and how to read anyone's OKF bundle as a graph.

OKF in one minute

An OKF bundle is a directory of markdown files. Each file is a concept: a table, a metric, a runbook, a person, anything. The rules are short:

• Every concept starts with YAML frontmatter, and that frontmatter has a type. This is the only required field.
• title, description, resource and tags are recommended. Any other key is allowed, and consumers must keep keys they don't know.
• Concepts link with standard markdown links, preferably bundle-absolute: [customers](/tables/customers.md). A link says that a relationship exists, and the surrounding prose says what kind.
• index.md and log.md are reserved in every folder, for listings and change history.

That's all conformance requires. Broken links, unknown types and missing descriptions must not make a consumer reject the bundle. Version 0.2 also adds optional fields for provenance and trust (sources, generated, verified, status, stale_after). They come up again near the end.

The point of the format is that nothing is locked in. If you can cat a file you can read it, and if you can git clone a repository you can ship it. An agent gets curated context without anyone building an integration.

Where a vault stands

The last row is the interesting one. OKF chose untyped links on purpose, and Typed Graph is built around typed ones. Further down you'll see that the two fit together better than you might expect.

Four habits that make the export clean

You can export any vault today, and the command fills in what is missing. The result is better when the notes already say what they are.

1. Give every note a type

This is the one hard requirement. A note without a type gets the default (Note, or whatever you pass as --default-type), which is conformant but tells an agent nothing. Choose types that a stranger would understand without context, because OKF has no central registry: Person, Paper, Runbook, API Endpoint. If you already keep schema notes in Types/, those names are your type list.

Multiple labels are fine. The export keeps the first as type and the full list as types, and Typed Graph reads both back:

---
type: Person
types: [Person, Engineer]
---

2. Write a one-sentence description

OKF consumers use description for index listings, search snippets and previews. It is what an agent reads before it decides whether to open the file. When a note has none, the export takes the first sentence of the first paragraph. Often that works. Sometimes it gets "This note is a draft." A description you write yourself is always better:

---
type: Runbook
description: Steps to triage a freshness alert on the orders pipeline.
---

3. Keep writing wikilinks, or switch edges to markdown links

You don't have to give up [[wikilinks]]. The export rewrites them as bundle-absolute markdown links and resolves short names the way Obsidian does. If you want the vault itself to render on GitHub and work with OKF tools without an export step, Typed Graph now accepts markdown links in edge lines too:

knows:: [[Bob]] {since: 2020}
knows:: [Bob](/People/Bob.md) {since: 2020}

Both lines produce the same typed edge. Relative paths (../Companies/Acme.md) work as well. Links to web pages are never treated as edges.

4. Don't call a note index.md or log.md

OKF reserves these names. The export renames such notes to index-note.md and log-note.md and updates links to them, but a name that says what the note is works better anyway.

Export: one command

tg export ./bundle --vault ~/vault --format okf --title "Research lab"

Here is the real report for the demo vault, which has 29 notes, typed edges, embeds and deliberate gaps:

Exported 29 notes to bundle as an OKF v0.2 bundle (38 files).

Change report:
    76  wikilinks rewritten as bundle-absolute markdown links
    29  titles added from the first heading or file name
    29  descriptions added from the first paragraph
     3  links to notes outside the export kept as links to not-yet-written concepts
    14  notes without a type given the default type
    13  {{edge: ...}} embeds replaced by their value as text
     2  list types reduced to their first entry as "type", the full list kept as "types"
     9  directory index.md files generated

Verified: tg okf check passes on the output.

Read the report as a to-do list. The 14 untyped notes are the guide pages, and giving them a real type (Guide, say) makes the bundle more useful. The 3 broken links are intentional stubs. OKF calls them "not-yet-written knowledge" and keeps them as links.

Every folder gets a generated index.md, so an agent can see what is there before it opens anything:

# People

* [Alice](Alice.md) - Alice runs search research at Acme.
* [Bob](Bob.md) - Bob builds the search backend.
* [Carol](Carol.md) - Carol works at Initech and contributes to two Acme projects.

The root index declares the version (okf_version: "0.2"). That is the only frontmatter OKF allows in an index file. The vault itself is never modified, and like the lat.md export, the command refuses to write into a non-empty folder unless you pass --force.

What happens to typed edges

This is the part I care about most. Here is a typed edge in Bob's note before and after:

works_at:: [[Acme]] {role: engineer, since: 2020}
works_at:: [Acme](/Companies/Acme.md) {role: engineer, since: 2020}

For an OKF consumer, the second line is a link to Acme with the words "works_at" in front of it. That is exactly how the spec wants relationships described: the specific kind is conveyed by the surrounding prose. An agent reading it understands the relationship. A graph view that treats every link as untyped still draws the edge.

For Typed Graph, the same line is still a works_at edge with two properties. So the export is not a lossy projection like the lat.md export. Load the bundle back and you get the same typed edges, with the same signs, targets and properties, and the same labels. A test in the repository checks exactly this. Only {{edge: ...}} embeds (expanded to their value) and ![[note]] transclusions (turned into links) don't come back.

You can publish one folder that OKF tools read as a knowledge bundle and Typed Graph reads as a typed property graph, without keeping two copies in sync.

Check any folder

$ tg okf check ./bundle
Checked 38 markdown files against OKF v0.2

3 warnings (consumers must tolerate these):
  Companies/Initech.md:12: link to Globex.md does not resolve in the bundle
  Papers/Typed Links in Practice.md:15: link to Property Graphs 101.md does not resolve in the bundle
  People/Mallory.md:12: link to Eve.md does not resolve in the bundle

Conformant with OKF v0.2

The check fails only on the spec's own conformance rules:

• a concept with no frontmatter or broken YAML
• a missing type, an empty one or a list
• frontmatter in a nested index.md
• a log.md date heading that is not YYYY-MM-DD

Everything a consumer must tolerate is a warning: broken links, wikilinks that OKF tools won't follow, missing descriptions, and the v0.1 timestamp key. It exits 1 only on errors and supports --json, so it fits in CI next to tg check. Google's sample bundles (acme_retail, ga4) pass it.

Reading OKF bundles as a graph

This works the other way too. Point the sidecar at any OKF bundle and turn on link edges:

OBSIGRAPH_VAULT=./ga4 OBSIGRAPH_DATA=./data OBSIGRAPH_LINK_EDGES=1 node server.mjs --stdio

Each concept becomes a node labeled with its type and titled with its title. Each prose link becomes a links_to edge, and a link to a concept that doesn't exist yet becomes a stub. Typed edge lines stay typed. Google's GA4 sample has 14 files, which give 14 nodes, 22 links_to edges and no stubs. After that it's an ordinary Cypher question:

MATCH (t:`BigQuery Table`)-[:links_to]->(m:Reference)
RETURN t.title AS table, count(m) AS metrics

table              | metrics
GA4 Events Export  | 7

Link edges are off by default, because turning every wikilink in an existing vault into an edge would change your graphs and queries. Typed edges written with markdown links work everywhere, including the Obsidian plugin. Plain link edges are a sidecar setting for now.

Trust fields are yours to write

OKF 0.2 lets a concept record who wrote it, who checked it and when it goes stale:

---
type: Runbook
description: Steps to triage a freshness alert on the orders pipeline.
generated: { by: human:volodymyr, at: 2026-10-06T09:00:00Z }
verified: { by: human:volodymyr, at: 2026-10-06T09:00:00Z }
status: stable
stale_after: 2027-04-01T00:00:00Z
---

The export keeps these fields when you write them and never makes them up. A vault doesn't know whether a person checked a note against its source, and a verified field the tool invented would be worse than none, because consumers derive a trust tier from it. If an agent will act on a note, mark it verified by a human: actor once you have actually checked it.

Checklist

• Every note has a type a stranger would understand.
• Notes an agent will read have a one-sentence description.
• No note is called index.md or log.md.
• Typed edges stay typed. Write them with wikilinks or markdown links.
• Run tg export ./bundle --format okf and read the change report.
• Run tg okf check ./bundle in CI.
• Add verified by hand where trust matters.

The commands are in the CLI reference, and the details of the format are in the OKF specification.

Want a starting point? The OKF ontology in the gallery is a data catalog (tables, metrics, dashboards, glossary terms, runbooks and owners) whose types already carry the keys OKF recommends, and its example notes export as a conformant bundle.