Open Knowledge Format

Knowledge for agents, edited by people.

The Open Knowledge Format packages what an organization knows as a folder of Markdown files that AI agents can read. Markify reads, browses and maintains those bundles without changing a line you didn’t touch.

Download Markify Read the OKF spec
OKF 0.2macOS 15.6Plain MarkdownNothing executed

The format

A bundle is just a folder.

No database and no server. If you can open a Markdown file, you can read OKF, and if you can commit to Git, you can ship it.

acme-knowledge/
├─ index.mdokf_version, listing
├─ log.mdhistory, newest first
├─ metrics/
│ ├─ revenue.mdtype: Metric
│ └─ gross-profit.md
├─ tables/
│ ├─ orders.mdtype: Table
│ └─ customers.md
└─ playbooks/ …
01

Bundle

A directory of .md files organized by topic, with optional index.md listings and log.md histories at any level.

02

Concept

One Markdown file with YAML frontmatter. Only type is required; title, description, resource and tags are recommended.

03

Links

Ordinary Markdown links between concepts, preferably bundle-absolute like /tables/orders.md. A broken link is knowledge not written yet.

Reading

Status, trust and freshness above the title.

In the Rendered lens a concept’s frontmatter folds into one row of chips. Plain notes look exactly as they always have; the badges appear only when a file declares a type.

  • Type in the accent color, then Draft or Deprecated when the status isn’t stable.
  • Stale once stale_after has passed.
  • The trust tier from verified: ✓ Reviewed by a person, Machine-confirmed, or Unverified.
  • The resource as a link to the asset the concept describes.
  • ⌘-click any link to follow it. A link to a concept that doesn’t exist yet offers to create it.

Plain files

The source stays yours.

Switch to the Markdown lens and it’s the same YAML you wrote. Markify parses frontmatter with a real YAML reader but never re-serializes it: every change rewrites only the key it touches.

  • Comments, key order and your own extension keys survive every edit.
  • Nested fields like verified, sources and executor are understood, including the single-mapping shorthand.
  • Everything is undoable as one step.
---
type: Metric
title: Revenue
description: Recognized revenue for a fiscal year.
tags: [finance, revenue]
status: draft
# owned by the finance data team
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ana, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - { id: rev-policy, resource: https://wiki.acme/revenue }
---

Bundles

The whole bundle, in the sidebar.

Choose File › Open Bundle Folder… (⇧⌘O) once and Markify remembers it. The Knowledge section of the sidebar (⌃⌘S) then shows every concept.

  • Browse by folder, by type, or by tag. Search filters by title, description and tag.
  • Linked from lists every concept that points at this one, including through sources and other path fields.
  • Issues are checked as you type: missing type, bad timestamps, unknown statuses, broken links.
  • The bundle is rescanned when files change on disk, whether you, Git or an agent changed them.

Provenance & trust

Where a fact came from, and who checked it.

Below the browser, the sidebar shows what the current concept’s frontmatter says about itself, so a reviewer can judge it without reading YAML.

  • When it last changed and who changed it, and when and by whom it was last verified.
  • Each source with its credibility signals: author, usage count and last change.
  • Footnotes keyed to a source show that source in their tooltip.
  • Attested Computations show their contract (runtime, parameters, executor, attester) as links. Markify shows the contract; it never runs a computation.

Authoring

Maintain a bundle without hand-editing YAML.

The Knowledge menu, under the … button, covers the chores that keep a bundle trustworthy.

  • Make Concept adds a type, suggesting the types the bundle already uses.
  • Mark Verified adds { by: human:you, at: now } to verified. Set your ID in Settings › General.
  • Status switches between draft, stable and deprecated.
  • Add Log Entry writes a dated entry to the folder’s log.md, newest first.
  • Rebuild Index regenerates index.md from each concept’s type, title and description.

Links that keep up

Type ](/ to pick a concept from the bundle. After Rename or Move To, Markify offers to update every link that pointed at the old location, keeping absolute links absolute and relative links relative.

Honest authorship

OKF separates who wrote a concept from who confirmed it. When you edit a concept’s text, Markify records you in generated, at most once a day. You can turn this off in Settings.

Apple Intelligence

“Suggest title, type & tags” also proposes a one-sentence description, merged key by key. AI text you keep in a concept is recorded as apple-intelligence in generated. It all runs on device.

Spec coverage

OKF 0.2, section by section.

Markify follows the spec’s conformance rules as a consumer: it reports problems, and never refuses a bundle for missing optional fields, unknown types or keys, broken links or a missing index.

SpecTopicIn Markify
§3Bundle structureRoot found from the nearest index.md with okf_version, the library, or a folder you open. index.md and log.md are treated as reserved.
§4Concepts & frontmatterAll recommended fields read; extension keys kept untouched.
§5.1Provenancesources, credibility signals and usage_window shown; footnote attribution in tooltips.
§5.2–5.3Trustgenerated and verified (including a bare mapping) read and written; trust tier badge.
§5.4–5.5LifecycleStatus badge and menu; stale badge from stale_after.
§6Links & pathsAbsolute and relative links, path-valued fields, backlinks, completion, updates on move, relative links in HTML export.
§7ActorsAgents, human: and process: recognized; you are recorded as human:<id>.
§8–9Index & log filesChecked for structure; rebuilt and appended on request.
§10Attested ComputationsContract shown and validated (runtime required); never executed.
§11ConformanceErrors, warnings and notes per file and per bundle.
§12–13VersionsNewer versions read best effort with a notice; v0.1 timestamp and # Citations used as fallbacks.

No execution

Computations, executors and attesters are displayed, not run. That belongs to the agent that consumes the bundle.

Folders you allow

Markify is sandboxed. Bundle-wide features work in your library folder and in folders opened with Open Bundle Folder.

Unpacked bundles

Zip and tarball bundles need unpacking first. There’s no graph view; links show as lists in the sidebar.

Open a bundle and start reviewing.

Free, native, and entirely on your Mac. Your knowledge stays plain Markdown in folders you control.

Download for MacApple silicon · v2.5.3 Implementation notes

Have an Intel Mac? Download for Intel