Open Knowledge Format.

The Corvair Knowledge Substrate writes one OKF record per document and treats it as the record of truth. Its search tables can be rebuilt from the records with no model call.

Open Knowledge Format

The Open Knowledge Format (OKF) is an open, vendor-neutral standard from Google Cloud for keeping knowledge as plain Markdown files, each with a short block of YAML front matter that describes it. The specification is published under the Apache 2.0 licence at github.com/GoogleCloudPlatform/open-knowledge-format.

Corvair Knowledge Substrate uses OKF as its own core format, not only for export. Every document it reads is kept as one OKF bundle, and that bundle is the record of truth. The index database is built from the bundles and can be rebuilt from them at any time, with no model call. Any tool that reads OKF can open a bundle, and a base can be exported as standard OKF and taken elsewhere intact.

What the standard provides

The Knowledge Substrate writes OKF 0.2, the current version. These standard fields carry most of what a reader needs.

FieldWhat it records
type, title, descriptionWhat the entry is, and a short summary of it.
generatedHow and when the content was produced: the reading pipeline and its version, or the service that generated it.
sourcesWhere the content came from: the file or page, its author and when it last changed. A footnote ties each passage and claim to its source.
verifiedEach check made, by a machine or by a person. From these, OKF's trust level follows: unverified, machine-confirmed or human-reviewed.
status, stale_afterDraft, stable or deprecated, and the date after which the content is stale.
log.mdA dated history of changes to the bundle, newest first.
A document's front matter, simplified
type: document
title: Halden supply agreement, version 3
description: Supply terms between Northcott and Halden, including notice and price review.
generated: { by: cks-ingest/2.4, at: 2026-11-08T10:14:00+08:00 }
sources:
  - { id: s1, resource: halden-supply-v3.pdf, author: Halden Ltd,
      last_modified: 2026-10-30T09:00:00+08:00 }
verified:
  - { by: cks-claim-check, at: 2026-11-08T22:05:00+08:00 }
status: stable
stale_after: 2027-11-08T00:00:00+08:00
x-cks:   # the Knowledge Substrate's extension block, below
Sample data. Every time carries its time-zone offset, as OKF 0.2 requires.

What the Knowledge Substrate adds

OKF readers must accept keys they do not know. Everything the standard does not cover is kept in one extension block, x-cks, so any OKF reader can still open the bundle and simply skip what it does not use.

ExtensionWhat it holdsWhy it is needed
Source tierTier 1 to Tier 4: licensed expertise, your own content, outside sites, or generated.OKF's trust level says who checked the content. The source tier says where it came from. Both are kept.
Claims and their checksEach claim's exact text, the passage it came from, and the result of its check.So the index can be rebuilt without reading the document again.
Topics and termsThe base's topics, keywords and named things, with their other names.Search by other names and spellings.
Typed relationshipsSupersedes, cites, supports and contradicts, between documents and claims.OKF links carry no type.
ClassificationSensitivity, personal data found, and language.Not yet in the standard.
Fingerprint and entitlementA fingerprint of the source's bytes, how it was collected, and who may use it under which licence.Integrity, and licensed content.
ValidityHow fast this kind of content goes stale.The standard keeps only the resulting stale_after date.

How it is kept current

  • Pinned to the standard. The Knowledge Substrate pins an exact version of the specification from Google Cloud's repository, and checks that repository at each release.
  • The extension is versioned on its own. A change to x-cks never breaks a reader of the standard fields.
  • Moving to the standard as it grows. When OKF adds a field for something the extension already holds, bundles move to the standard field, and readers accept the old one for one release. OKF 0.2's sources, generated and deprecated status replaced three of the Knowledge Substrate's own fields this way.
  • Proposed upstream. Extensions that would help others, such as fingerprints, sensitivity, licences and typed links, will be proposed to the standard.
  • Export is plain OKF. An exported base is standard OKF bundles with the extension block alongside, so it can be read without Corvair.

The record

The Knowledge Substrate writes the record as the document is read. Each load is a new version. Nothing is edited in place. One record holds these parts.

PartWhat it holds
Front matterWhere the document came from, its source tier and its source role.
DescriptionA summary, with the document's topics and tags.
Section entriesThe passage text and where each passage sits in the document.
Entity entriesNamed things in the document, with their other names.
LinksLinks to other documents: which one it supersedes and which it cites.
Claim entriesThe claims taken from the document. Present only when claims are on for the base.

The tables built from it

The Knowledge Substrate builds its search tables in the index database from the records. No model call is needed. The links between claims are the one thing kept outside the records, because a scheduled link run produces them.

One record per document, in Open Knowledge Format Written as the document is read. Each load is a new version; nothing is edited in place. Front matter · Description · Sections · Named things · Links · Claims built from it reads claims, writes nothing back Search tables Passages, topics, terms, tags and claims. Built from the records with no model call. They serve search, answers, heat maps and the Canvas. Claim links Supports, depends on, contradicts. Found by a scheduled link run, and kept beside the records, not in them.
TableWhat it holdsBuilt from
DocumentsOne row per document: tier, type, source role, dates, summary and keywords.The record
PassagesPassage text, heading path and location, with the indexes that search uses.The record
TopicsThe base's topics, and which documents carry each.The topic map and the tagging step
Terms and aliasesKeywords and named things, their other names, and where they appear.The tagging step
Document linksWhich document supersedes or cites another.The record
ClaimsOne row per claim: its document, passage, text and the result of its checks.The record
Mentioned togetherPairs of terms and how many documents share them. A stored query, refreshed after each load.The tables above
Claim linksLinks between claims, every pair judged, and the weight of each claim.The link run, not the record

Because the record is the source of truth, a table that is lost or changed is rebuilt from the records. Claim links are not in the records. To get them back, run the link run again or restore the database backup.

The state of a library's records: the record store compared with the search index, records written each day, trust tiers, and checks against the format

The catalog round trip

A catalog is where an organisation lists the knowledge it holds. Because the Knowledge Substrate already keeps its knowledge as OKF, it reads and writes what a catalog exchanges. The exchange runs both ways, and it is not tied to one catalog product.

DirectionWhat happens
The Knowledge Substrate into the catalogThe Knowledge Substrate publishes its records to a place the catalog reads. The catalog then lists them and serves them to its own agents.
The catalog into the Knowledge SubstrateThe Knowledge Substrate reads OKF from a catalog and loads it like any other source. It needs no custom extractor.

Into the catalog

The records the Knowledge Substrate already keeps are what it publishes. Extra Knowledge Substrate fields sit under their own key. A reader that does not know them ignores them, and the record stays valid OKF.

Into the Knowledge Substrate

When the input is already OKF, the Knowledge Substrate skips parsing and extraction. It checks that the record is valid, loads it, and builds the same tables as for any other document. Where a catalog holds metadata in another shape, a small adapter turns it into OKF first, so the Knowledge Substrate sees one format whichever catalog it came from.

Agents that find knowledge in a catalog can call the Knowledge Substrate over MCP for the rest. See API, MCP and the command line.

Connect your first assistant.