Open Knowledge Format (OKF)

You are learning a move

No active mission. Use this page to improve one real decision; reading alone is not proof.

How can people and agents share knowledge without locking it inside one tool?

Open Knowledge Format (OKF) is a vendor-neutral way to package knowledge as plain Markdown files with YAML frontmatter. A person can read the files directly. An agent can filter the metadata, follow the links, and load only the concepts relevant to its task.

The core move is simple:

knowledge trapped in a tool
→ one concept per Markdown file
→ queryable facts in frontmatter
→ relationships as normal links
→ a portable bundle any consumer can read

OKF defines the portable floor, not the full knowledge system. It does not decide whether a claim is true, whether an agent may act on it, or how a team should write. Those decisions remain with the producer, consumer, and human authority.

Smallest Useful Bundle

Start with one directory and one concept:

support-knowledge/
├── index.md
└── policies/
    ├── refund-window.md
    └── return-exceptions.md

The concept can be as small as this:

---
type: policy
title: Refund Window
description: Customers may request a refund within 30 days of delivery.
tags: [support, refunds]
status: stable
stale_after: 2027-01-31
sources:
  - id: terms
    resource: https://example.com/terms
    title: Customer Terms
---

Use the delivery date, not the purchase date, to calculate the 30-day window.

See the companion `return-exceptions.md` concept for damaged or regulated
goods.

Only type is always required by OKF v0.2. The other fields earn their place because they help a consumer identify, retrieve, and judge the concept before reading the body.

A producer writes or exports the files. A consumer—such as a person, search index, knowledge catalog, or AI agent—reads them without needing the producer's software. That separation is the main interoperability benefit.

Use the Bundle

For each task, a consumer can make a cheap decision before loading the full body:

1. Find concepts by path, type, title, description, or tags.
2. Filter deprecated or stale concepts.
3. Check provenance and independent verification at the risk level the task requires.
4. Read the body only after the concept passes those gates.
5. Follow Markdown links to gather related context.
6. Stop or escalate when evidence or authority is insufficient.

For example, a support assistant may use the refund concept above to explain a standard case. It should stop before approving an exception if the linked exception policy is missing, stale, or outside its delegated authority. OKF makes the context portable; it does not grant permission.

Portable Native Profiles

A portable knowledge policy should unify meaning without flattening every wiki into one grammar. It names profiles for distinct surfaces, then lets each profile declare its page types, templates, lifecycle field, depth field, required metadata, and relationship vocabulary.

The public Playbook profile uses:

• type for the reader job;
• template for the teaching shape;
• loop_phase for intention, action, or evolution;
• level for entry, working, or deep; and
• the eight relationship labels documented below.

Another knowledge surface may use different field names or relation spellings. That difference is meaningful. Aliases may repair variance inside one profile, but they must not silently translate relations between profiles. A depends-on teaching edge and a similarly named operational dependency can remain distinct while both participate in a portable artifact envelope.

The safe public projection contains public locators and portable metadata only. It never needs the private source path, workflow state, baseline, or control that produced the teaching.

What v0.2 Adds

Google Cloud introduced Open Knowledge Format in June 2026 as an open specification for portable AI context. Version 0.2 keeps the core shape simple:

• a directory of markdown files
• one concept per file
• YAML frontmatter for queryable fields
• normal markdown links as graph edges
• optional index.md files for progressive disclosure
• optional log.md files for chronological history

type remains the only required field. The trust fields are optional. A v0.1 concept remains consumable because v0.2 consumers can fall back from generated.at to legacy timestamp, and from sources to a body Citations list.

A bundle may declare okf_version: "0.2" only in the bundle-root index.md. Individual concepts and nested indexes do not own the bundle version.

That makes OKF a portable evidence envelope, not a complete writing or trust standard.

Agentic Trust

An agent should not need to read a concept's body before deciding how much attention or authority it deserves. OKF v0.2 moves five decision signals into frontmatter:

Signal	Reader question	What it carries
sources	Where did this come from?	Resource, author, usage count, and last modification when known.
generated	Who produced this version?	Actor and generation time.
verified	Who independently checked it?	One or more confirming actors and times.
status and stale_after	Is it current enough for this decision?	Draft, stable, or deprecated state plus an absolute review date.
Attested Computation	Was this value calculated through the sanctioned path?	Runtime, declared parameters, computation, executor, attester, and execution receipt.

These signals support three useful trust tiers:

• Unverified — no independent confirmation is declared.
• Machine-confirmed — another machine actor checked the concept.
• Human-reviewed — a human actor independently confirmed it.

The tier does not decide whether the concept may be used. The consumer applies the threshold appropriate to the consequence. An executive dashboard may require human-reviewed financial values. A disposable experiment may accept an unverified idea.

Worked Trust Decision

Suppose an agent finds three concepts named “Revenue”:

Candidate	Visible signal	Suitable use
A	No verified field	Exploration where an incorrect answer is cheap and clearly labelled.
B	Machine verification, current stale_after	Automated monitoring under a policy that accepts machine-confirmed knowledge.
C	Human verification, current policy source, stable status	A consequential executive decision, if the consumer's policy requires human review.

The consumer chooses the threshold. OKF exposes the signals without pretending that one universal score can make the decision.

Do not add a universal credibility score. A score hides the reader's policy, compresses unlike evidence into one number, and begins going stale as soon as it is written. Portable signals should travel with the concept. Judgment should remain with the consumer.

Decision-Supporting Pages

Portable OKF answers whether a concept can travel. A local profile may also help a reader decide whether to use it. Keep that extension small and explicit:

Signal	Reader question
page_job	Which decision or action does this page support?
Use boundary	When does the page apply?
Avoid boundary	When should the reader choose another authority?
Evidence state	Is the claim observed, measured, inferred, proposed, or stale?
Review signal	What observable change would invalidate or reopen the guidance?

These are local decision aids, not new OKF v0.2 requirements. A portable consumer must still accept parseable frontmatter with a non-empty type. Repositories may choose their own extension keys while preserving unknown metadata.

An executable proof owner may also record the observed cost of a reproducible proof. State the command, measurement, date, environment, and sample count. Treat this as historical evidence, not a runtime budget, service level, or invented percentile. Omit it when no fresh measurement exists.

Attested Values

Attestation matters when the displayed value must come from one approved calculation.

declared computation + bounded parameters
→ sanctioned executor
→ execution receipt with job identity and executed query
→ deterministic attester
→ display or reject

The agent supplies declared parameters instead of improvising a query. The executor records what ran. The attester compares that execution with the approved computation. A changed table, missing join, or undeclared parameter blocks the value.

Attestation proves conformance to the sanctioned calculation. It does not prove that the policy, source data, or business definition is correct. Those remain human-owned evidence and governance decisions.

Local Mapping

OKF convention	Dreamineering standard	Local rule
type frontmatter	Page Types	type means page job: hub, concept, playbook, industry-performance, and so on.
Trust frontmatter	Wiki Schema	Preserve sources, generated, verified, and stale_after; derive trust at read time instead of storing a credibility score.
Attested computation	Stackmates execution controls	Public pages may teach the contract; sanctioned execution, receipts, and attesters remain operational controls.
Markdown file	Documentation Writing Standard	A page must stand alone without private project context.
File path as identity	Naming Standards	Route and filename are stable semantic handles.
index.md hierarchy	Index Page Standard and Hub Index Template	Index pages route before they teach.
YAML frontmatter	Wiki Schema	Frontmatter is queryable map data, not decoration.
Markdown links	Information Architecture Standard	Links should carry scent and typed relationship intent.
log.md history	Wiki-log pattern	Public pages teach current truth; the private wiki log records schema evolution.

Local Deviations

Dreamineering follows OKF's portable shape, but it changes three operating details on purpose.

• No per-directory log.md. The public bundle does not carry local process history beside each page. Schema and routing changes close into private controller receipts under .AGENCY/.NAVIGATION/CONTROLLER-RECEIPTS/.
• Private generated global index. The repo keeps a generated CONTENT-MAP and boot index as local agent discovery surfaces. They are a local extension beyond OKF, not public teaching pages.
• Hub index.mdx pages route readers. Public folder indexes are the progressive-disclosure layer. They help people and agents choose the right child page before reading deeply.
• Native lifecycle fields remain native. The Playbook keeps loop_phase for its intention, action, and evolution cycle. Exporters may add portable OKF status without silently reinterpreting local workflow meaning.

Meaning Graph Extension

Dreamineering extends OKF with a meaning graph. The graph keeps the portable markdown shape, then adds enough local structure for agents to rank, traverse, and prove ideas.

OKF page node -> DDL concept node -> typed edge -> proof signal -> centrality -> belief mass

The five-part stack is:

Layer	Job
Node	A page route or DDL concept that can be addressed by agents.
Term	A DDL name with a stable home route in /playbook/agents/ source data.
Edge	A typed Context link that says how one idea relates to another.
Proof	A proved-by edge or proof-state signal that keeps claim strength tied to evidence.
Weight	A derived centrality score from the graph. Editors do not hand-write PageRank scores into source files.

The local metadata envelope is:

• type and template name the page job and writing pattern.
• profile is a valid page type when one actor's relevant ideas, choices, evidence, and limits are the subject.
• page_job names the exact reader decision or operating action the page supports.
• pillar names the 5P role when a page belongs to a business or industry function.
• loop_phase places the page in intention, action, or evolution.
• level says whether the page is entry, working, or deep.
• DDL home binds canonical terms to playbook routes.
• typed_edges come from Context bullets.
• proof_state is claim-state evidence when a page has it.
• centrality is derived by the graph generator only.

Reality maps use type: map-of-reality and generator_skill: drmg-map-reality. This is the local OKF extension for Markdown files named *REALITY*. It is the first part of the Dreamineering method: know the truth of what you have to deal with before imagining the Dream or choosing the Bridge. The page must expose true current state: existing artifacts, assets, code, diagrams, proof, and gaps.

Business and industry pillar pages use job-specific type values so the graph can read the Tight Five without opening the body:

Function	Type family	Required helper fields
Industry principles, performance, platform, process, players	industry-*	pillar, page_job
Business principles, performance, platform, process, players	business-*	pillar, page_job

Examples:

type: industry-performance
pillar: performance
page_job: "Gauge the industry with KPI baselines, benchmark thresholds, and good-vs-bad signs."

type: business-platform
pillar: platform
page_job: "Map the capability's assets, tools, standards, and operating infrastructure."

Do not use domain-map when the page job is one 5P pillar. domain-map is for the broader territory map.

Use this Context pattern for graph edges:

- **depends-on** [DDL Nomenclature](/playbook/language/symbolic/ddl-nomenclature) — terms need a canonical meaning before they can become graph nodes.

The live relationship labels are:

• depends-on — the source cannot be understood or trusted without the target.
• pairs-with — the ideas naturally co-activate.
• applies-to — the source concept is used in the target domain or method.
• instance-of — the source is a concrete example of the target pattern.
• contrasts-with — the source is clearer against the target foil.
• proved-by — the target supplies proof for the source.
• risk-governed-by — the target bounds risk, authority, or misuse.
• redirects-to — a compatibility route resolves to the canonical page.

## Context is the only section that creates typed edges. ## Zoom Out is routing prose with ordinary links. Normal markdown links still count as weak edges, while typed Context links carry more graph weight.

proved-by carries the most weight; the taxonomy module owns the remaining weights. The kb-smart-links skill owns this vocabulary operationally. The generator rejects labels outside it.

Agent Knowledge Contract

Agent-facing knowledge has one extra rule: a page must say whether it is source, projection, discovery, execution, or proof.

Layer	Home	Job
Source	/playbook/agents/	OKF-readable markdown that names current language, capability, evidence, receipts, services, and loops.
Discovery	agent.json, llms.txt	Concise machine-readable entry points for external agents.
Delegation	Delegation	Decision rights that bound act-alone, ask-first, escalation, and refusal cases.
Execution	Skills, hooks, and Stackmates drmg	Procedures and build loops that make the contract operational. Playbook search loads existing knowledge, kb-enrich writes back universal lessons, and kb-edit-playbook conducts page edits.
Proof	receipts, capability mirrors, Stackmates evidence	Closed-loop evidence of what is REALITY, DREAM, or CONSUMED.

The recovered /playbook/agents source layer now carries these OKF-readable children:

• Agent Operating Model — identity, capability contracts, machine-readable surfaces, and trust signals.
• DDL Nomenclature — canonical human-readable agent language.
• Dreamineering Symbols — DML and A&ID wire-format notation.
• Language Crosswalk — term-to-symbol binding across language densities.
• Actions And Consequences — profile-led action design for agent-facing artifacts.
• MCP Toolkit — connector reality, desired posture, classification, and human-owned remediation.
• Agent Funnel — discovery-to-receipt path for agent consumers.

Design Decision

Treat OKF as an interoperability benchmark, not the source of truth.

OKF is the port, not the ship. It makes knowledge portable. It does not decide whether a claim is true, current, safe, useful, or wise. A working memory system needs a stricter local profile for evidence, decisions, outcomes, lessons, visibility, purpose, and lifecycle.

For learning memory, keep two update modes distinct:

Memory surface	Update rule	Why
Evidence, decisions, outcomes, lessons	Append and supersede	Learning requires the historical reason and consequence.
Compiled knowledge	Rewrite from current evidence	Readers need one usable current explanation.
Indexes, graphs, embeddings, context packets	Rebuild	Derived retrieval state must never become source truth.

Export is an authority boundary. Filter visibility and purpose before ranking. Export only explicit portable fields. Rebuild public text from an approved portable body or description; do not copy private deliberation or unknown fields into a public bundle merely because they parse as valid YAML.

Start retrieval with the cheapest measurable baseline. Add graph traversal for relationship questions. Add embeddings or reranking only after real queries show that the simpler path misses valuable evidence at an acceptable cost.

Dreamineering pages should be easy to export toward OKF because they already use markdown, frontmatter, semantic paths, and links. They should not weaken their local contract to match OKF's minimum. A touched page still needs the stricter page-type/template match described in Page Types.

From Portable Knowledge to Shared Wisdom

OKF v0.2 makes knowledge portable and exposes trust signals. It does not make the knowledge valuable, teachable, or transferable. Dreamineering adds those requirements through the Wisdom Transfer Standard.

Use this layered path:

OKF portability
→ visible provenance and trust boundary
→ worthwhile reader decision
→ ZPD-sized practice with contingent support
→ independent second-context performance
→ evidence returned to the canonical owner

Layer	Default control	Pit-of-success result
Portable	type, Markdown, bundle structure, and links	A consumer can load the concept.
Trust-aware	Sources, producer, verifier, lifecycle, and freshness	A consumer can calibrate use or refuse.
Valuable	description, page_job, beneficiary, and retrieval trigger	The reader knows why this concept deserves attention.
Teachable	Independent state, proximal move, MKO, scaffold, and fading	The reader can begin without surrendering judgment.
Transferable	Independent and second-context proof	Assisted output is not mistaken for learning.
Self-improving	Review trigger, evidence return, and one canonical owner	Use can improve or retire the concept.

These are local teaching and governance requirements, not new OKF core fields. Preserve OKF v0.2 interoperability. Add local metadata only when it changes retrieval, trust, teaching, action, or review. Put teaching detail in the body when no portable field owns it.

The default retrieval sequence is:

1. Find the concept from its job and retrieval trigger.
2. Inspect provenance, confidence, freshness, and human authority.
3. Follow typed links to prerequisites, evidence, risk, and application.
4. Choose one valuable action at the learner's current edge.
5. Use support only as long as it improves the next attempt.
6. Test independent use in a second context.
7. Return evidence to the canonical owner or stop at the named authority boundary.

An OKF bundle falls into a pit of success when the easiest valid route ends in better judgment, independent action, or a correct refusal—not merely a retrieved answer.

Write–Sweep–Promote

Keep an OKF bundle healthy through three bounded loops.

Write

Validate the one concept that changed. Confirm its required shape, preserve existing and unknown values, and reject unsupported freshness.

Sweep

Inspect the wider bundle without rewriting it wholesale. Rank findings and advance one bounded candidate. Check links, producers, generated maps, indexes, ownership boundaries, and retrieval impact.

Promote

Promote automatically only when a change is mechanical and reversible, such as adding a schema-exact missing field without changing an existing value.

Require a human decision for meaning, classification, authority, ownership, freshness, links, structure, deletion, publication, or retrieval strategy. A high score cannot overrule an integrity or privacy failure.

Human-in-the-loop packet

Bring the human one decision:

Candidate:
Recommended move:
Evidence:
Risk:
Exact change:
What happens if we wait:
Next review trigger:

Humans approve judgment. Agents perform deterministic checks, generation, and evidence collection.

Health setpoint

An OKF bundle is healthy when changed concepts pass fast checks; missing required metadata does not increase; generated output changes through its producer; unknown fields survive; links and maps are current; failed research stays visibly unknown; consequential changes name a human; and each run ends with one bounded trigger.

Healthy does not mean finding-free. It means drift is visible, ranked, and routed to the right authority.

Five-question self-audit

1. Identity: What agent question does this concept answer, and would deletion remove capability or only clutter?
2. Connection: Can an agent traverse to related concepts through explicit links?
3. Trust: Can the file distinguish verified fact, inference, unknown, producer, source, lifecycle, ownership, and freshness without hidden context?
4. Retrieval: Do the ten likeliest queries rank the correct concept first, and what is the false-positive rate?
5. Compounding: What smallest correction now is likely to improve future agent accuracy?

The autonomy test depends on delegated authority:

Can the agent perform the delegated action from the retrieved concept and its explicit links, or correctly stop at a named human boundary?

A correct refusal or escalation is successful agent behavior. Portability must not erase human authority.

Use This When

• checking whether a playbook page is machine-readable enough for external agents
• deciding whether an agent-facing contract belongs in /playbook/agents or should stay out of the public knowledge base
• deciding whether portable context is enough for an agent to act without asking Wik
• designing an export, manifest, or bundle format
• explaining why type, title, description, tags, links, and logs matter
• comparing local wiki rules to open knowledge-sharing standards

Checks

An OKF-aligned Dreamineering page passes when these signals are visible:

• type exists and matches Page Types
• page_job exists when the route is a repeated pillar, generated projection, or agent-facing operating page
• pillar exists when the route is a business or industry 5P page
• title and description explain the page job
• route and filename are stable semantic handles
• links have scent, not bare labels
• Context links use controlled relationship labels when they carry graph meaning
• DDL terms with homes resolve to real /playbook routes
• important pages have at least one proof edge or an explicit proof-state reason
• centrality is generated, not hand-authored
• current truth lives in public docs, while schema evolution is logged privately
• trust tiers are derived from verified actors rather than hand-authored as a credibility score
• stale_after is an absolute date when the concept has a known review boundary
• an Attested Computation names its executor, attester, declared parameters, and receipt before its value is displayed
• significant teaching passes all six non-averaged Wisdom Transfer gates
• support names how it fades and how independent second-context performance will be tested
• use has an evidence-return path to one canonical owner

Practice

Use this 15-minute exercise before converting a whole wiki:

1. Choose one concept that an agent often retrieves incorrectly or too slowly.
2. Put that concept in one Markdown file.
3. Add type, a clear title, a one-sentence description, and useful tags.
4. Add sources, generated, verified, and stale_after only when you have evidence for them.
5. Link one prerequisite or companion concept in the body.
6. Ask a second person or agent to find the concept from frontmatter alone, explain why it should or should not be trusted, and follow the link.
7. Give them one reachable action, fade the support, and test the capability in a second context.
8. Return the observed result to the canonical concept or its named review owner.

The metadata exercise passes when the second reader can make the retrieval and trust decision without hidden context. Transfer remains unproved until they act independently in a second context and the result returns to the owner. If either stage fails, improve the concept before expanding the bundle.

Validation

Test metadata through the decision it should improve.

1. Give an unfamiliar person or agent the title, description, type, tags, and Context links without the page body.
2. Ask it to identify the page's purpose, evidence boundary, canonical owner, and next useful route.
3. Compare the answer with the same task using only the filename and title.
4. Keep metadata that produces a clearer or safer decision. Remove metadata and process that adds no useful understanding.

Repository-wide debt counts, centrality scores, and generated graphs are not proof that an agent understands the project. Use automation only after a controlled comparison shows that it improves a real retrieval, trust, or action decision.

Failure Modes

• Minimum becomes ceiling — OKF requires type, but the local page still needs the right page type and template.
• Portable but weak — markdown exports cleanly, but links lack scent and agents cannot choose the next page.
• Path drift — the file path stops naming the concept clearly.
• Hand-authored mass — centrality is written into source data instead of derived from structure.
• Label drift — Context bullets invent relationship labels that the graph cannot compare.
• Log leak — private evolution history appears in public teaching prose.
• Score laundering — a hand-authored credibility number replaces visible provenance and consumer judgment.
• Self-verification — the producer is presented as an independent verifier.
• Portable but inert — a concept retrieves cleanly but gives the reader no valuable action, transfer proof, or evidence-return path.
• Scaffold hidden in metadata — local teaching requirements are presented as OKF v0.2 core fields or encoded where another consumer cannot interpret them.
• Attestation theatre — a value claims attestation without an execution receipt or deterministic comparison.

Changes my mind: a simpler interoperable format produces better retrieval, provenance, freshness, and trust decisions without sacrificing human readability or consumer independence.

Version delta: v0.2 adds optional decision signals for provenance, trust, freshness, lifecycle, and attestation while preserving v0.1 bundles.

Source Trail

• GitHub repository
• OKF v0.2 specification — canonical field, compatibility, lifecycle, and attestation contract.
• Google Cloud: OKF v0.2 adds trust signals — release rationale and examples.
• Google Cloud: Introducing the Open Knowledge Format — source article for OKF v0.1.
• Page Types — local page-job authority.
• Wiki Schema — local Map-First edit and frontmatter contract.
• Information Architecture Standard — local placement, links, and answer-engine rules.

Context

• depends-on Purpose — the Tight Five root for why a page exists.
• applies-to Shared Wisdom Loop — carries portable knowledge through judgment, teaching, independent transfer, and evidence return.
• risk-governed-by Wisdom Transfer Standard — prevents clean metadata from being mistaken for transferred capability.
• applies-to Dev Flow — OKF pages become valuable when they help agents trace demand, spec, build, commissioning, and feedback.
• pairs-with Platform — portable knowledge formats become useful infrastructure when the platform can consume them.
• proved-by Performance — retrieval and answer quality should be measured.

Questions

What would fail if this wiki were exported as an OKF bundle tomorrow?

Next question: Can a new reader build one valid concept and explain when an agent should refuse to use it?

• Which decision requires human-reviewed knowledge rather than machine-confirmed knowledge?
• Which page lacks a meaningful type?
• Which route depends on private context?
• Which links are present but carry no scent?
• Which generated projections need a portable manifest?