In brief
- A Knowledge Bundle is a self-contained directory of related knowledge documents.
- A Concept is one Markdown file; only the type metadata field is required.
- index.md supports progressive orientation, while ordinary Markdown links express relationships.
- OKF is a format – not a database, a RAG solution or a permission and quality process.
- As of 17 July 2026, OKF v0.1 is an early draft, not an established industry standard.
What problem is OKF intended to solve?
Important organisational context is often fragmented: definitions live in a data catalogue, procedures in a wiki, API notes in code and experience in the heads of individual people. New AI applications repeatedly have to assemble those relationships from incompatible systems.
OKF proposes a small, shared exchange structure. Knowledge remains in ordinary readable files, can be versioned with Git and can be produced and consumed by different tools. This reduces bespoke export formats, but it does not automatically resolve fragmented or contradictory content.
- Readable by people without specialist software
- Processable by agents without a proprietary SDK
- Transferable as a directory, Git repository or archive
- Suitable for organising traceable changes, provenance and relationships
How do Bundle, Concept, frontmatter and index.md work?
An OKF Bundle is a directory tree and the unit that is distributed. Each domain concept lives in its own UTF-8 Markdown file. The file path without its extension is the Concept ID, and ordinary Markdown links connect concepts to one another.
- Step 1
Knowledge Bundle
A self-contained directory groups knowledge for a domain such as support, sales or a data platform.
- Step 2
Concept
One Markdown file describes one unit of knowledge, such as a metric, table, API, policy or runbook.
- Step 3
YAML frontmatter
A metadata block begins the file. type is required; title, description, resource, tags and timestamp are recommended optional fields. Producers may add their own fields.
- Step 4
index.md and links
Optional index.md files guide readers through a directory without loading every detail immediately. Markdown links express domain relationships beyond the folder structure.
What could a small organisational example look like?
A service team creates a support/ bundle. The index.md file explains its purpose, validity and entry points. metrics/first-response-time.md defines the First Response Time metric, runbooks/escalation.md describes escalation and systems/ticket-api.md documents the responsible interface.
The metric file might carry the type Metric, a clear title, a link to the accountable source, tags such as support and sla, and a modification timestamp. Its Markdown body contains the calculation, exceptions and a link to the escalation runbook. A person can review the definition directly; an agent can use metadata and links to continue selectively.
- A Concept describes the metric, not the changing ticket values themselves.
- The resource link points to the accountable source or system being described.
- Domain links connect definition, data source and operating procedure.
- Git history can expose changes, but it does not replace domain approval.
How is OKF different from RAG, MCP and existing data systems?
OKF describes how curated knowledge can be exchanged in files. The other concepts answer different architecture questions. They can be used with OKF, but they are not substitutes for one another.
| Building block | Which question does it answer? | Relationship to OKF | Why OKF does not replace it |
|---|---|---|---|
| RAG | Which content is retrieved for a specific question and supplied to the model? | An OKF Bundle can be a curated RAG source. | RAG still needs search, ranking, permission filters and answer evaluation. |
| MCP | How does an AI application access resources and tools through a standard interface? | An MCP server can expose OKF content or update tools. | MCP is a communication protocol, not a knowledge format. |
| Database | Where are structured, changing or transactional values stored? | OKF can document schema, meaning and correct use. | OKF provides no query, consistency or transaction logic. |
| Data catalogue | Which data assets exist, who owns them and how are they governed? | OKF may serve as a portable import or export format. | A catalogue operates search, inventory, workflows and governance features. |
| llms.txt | Which web content does a site want to make easier for language models to discover? | Both use simple text formats but pursue different goals. | llms.txt is a website-oriented guide while OKF is a linked knowledge package. |
Which governance responsibilities still remain?
Readable and portable files are not automatically correct, current or authorised for every reader. The OKF specification defines neither a permission model nor a fixed taxonomy, approval workflow or retention rule. The organisation must design those controls around the Bundle.
- Assign a domain owner, validity and approval status to each Concept
- Classify confidential content and restrict access to the repository, exports and consumers
- Review automatically generated content and support claims with sources
- Define change, deletion and archive rules
- Preserve unknown and producer-specific metadata when processing files
- Protect consumers against broken links, manipulated content and unexpected file sizes
When is a pilot worthwhile – and when should you wait?
A small pilot makes sense when knowledge already lives in Markdown or versionable documentation, multiple agents or tools need the same context and portability offers a concrete benefit. Choose a bounded domain, define accountable sources and test export, import, links and updates with at least two consumers.
Wait or observe when one existing system already meets the need, permissions remain unresolved or contracts require a stable long-term specification. With an early draft, converters, metadata and versions should remain replaceable.
- Step 1
Choose a bounded domain
Begin with a small set of authoritative concepts and a clear user problem.
- Step 2
Add governance
Define ownership, classification, approval, updates and access outside the format.
- Step 3
Prove portability
Read, validate and version the same Bundle with different tools.
- Step 4
Track development
Record the specification version and reassess changes before a broader rollout.
Mini-example: sharing knowledge about a support metric
The organisation exports the definition, accountable data source and escalation procedure into a small OKF Bundle. An analytics agent uses the metric definition, a support agent follows the linked runbook and employees review both files in Git. Live ticket values remain in the operational database and are retrieved through a controlled API; access rules apply independently of the format.
What to remember
Consider OKF as a lightweight exchange layer when knowledge should move between people, agents and tools. Pilot it on a small scale and deliberately add permissions, domain ownership, quality controls and version management.
Sources and further reading
These primary sources provide further detail on definitions, technical foundations or responsible use.
Content reviewed