DEV Community: Julien Chable

A folder of markdown you can actually browse: OKF4net 0.7 and the interactive okf-render

Julien Chable — Fri, 16 Oct 2026 12:23:33 +0000

An Open Knowledge Format bundle is a directory of markdown files with YAML frontmatter. That is what makes it good for agents and for code review: an agent reads it with cat, a reviewer reads a change as a plain diff, and git does the rest. It is also what makes it tedious for a person to browse. Open the folder and you see file names; open a file and you see one concept, with no idea what links to it.

OKF4net, our independent .NET implementation of the OKF spec, ships a site generator, okf-render, for that person. Up to 0.6.0 it wrote a plain static site. Since OKF4net 0.7.0 it writes an interactive viewer. Here is a tour, then how it is built and tested, then what else changed in the release.

In (very) short

okf-render <bundle> --out <dir> writes a folder of static files. Open index.html from disk: no server, no network, nothing to install in the browser.
Concept pages get a tree explorer with trust and staleness marks read from each concept's frontmatter; every page gets a Jump to palette (Ctrl+K or /) and a light/dark theme.
Each concept page draws its Neighbourhood, the concepts it links to and that link to it, and a separate page draws the whole bundle's link graph with facets, a detail drawer and shareable graph.html#<concept id> addresses.
Every drawing has a text equivalent and a keyboard path. The graph is one tab stop; the arrow keys walk from a node to its neighbours.
Under the hood: no new runtime dependency, a graph layout that gives the same positions in Chromium, Firefox and WebKit, a DOM sanitizer as the whole defence against hostile markdown, and a test harness that runs the real scripts.
Also in 0.7.0: okf is now a dotnet tool you can pin in a repository's tool manifest for CI, a hardening wave closes a few ways to crash or fool the library, and four changes are worth checking when you upgrade (the list).

The problem: easy to diff, hard to browse

OKF is Google's open format for knowledge that both people and agents read. A bundle is a directory tree of markdown files. Each file is a concept: a YAML frontmatter block (type is the only required field; title, description, tags, status and others are common) and a markdown body. A concept's id is its path without .md, and concepts link to each other with ordinary markdown links. The spec also defines provenance and trust fields: verified records who reviewed a concept and when (§5.2), and stale_after says when it should be looked at again (§5.5).

OKF4net implements v0.2 on the .NET base class library alone (its own YAML-subset parser and link scanner, no third-party packages), built from the spec rather than ported from another implementation. Besides the library it ships two Native AOT tools: okf, which validates, audits and formats bundles, and okf-render, which turns one into a website.

Here is what okf-render 0.6.0 produced for a concept of acme_retail, the sample bundle in the repository:

One page per concept, the frontmatter as a table, the body rendered, links that work, and an index page. It was correct, and it answered none of the questions you have while reading: where am I in the bundle, what else is there, who points at this, and can I trust it.

In short: an OKF bundle is easy for agents and diffs, hard for people to browse. okf-render used to write one flat page per concept; the new version turns those pages into a viewer.

One command, a folder of files

The command is the same as before:

okf-render bundles/acme_retail --out ./acme-site
# then open ./acme-site/index.html in any browser: double-click it

What it writes is still a folder of plain files: index.html, one page per concept at the concept's own path (computations/gross-margin-period.html), a graph page for the whole bundle, and an assets/ folder with the stylesheet, the scripts, the fonts with their licences, and one generated data file, okf-index.js. The graph page is graph.html in the usual case, and the rest of this article calls it that; if a concept already owns that name (a root-level graph.md, say), okf-render picks graph-1.html, then graph-2.html, and so on, and the header link follows. Nothing is fetched from the network when a page opens, so the folder works from file://, from a USB stick or from any static host. okf-render itself is a self-contained Native AOT binary: the machine that renders needs no .NET runtime.

It is deliberately a separate binary from okf, the small validator that runs in CI, so that okf does not carry what only a website needs: a vendored copy of marked to render markdown in the browser, and three embedded font families.

Getting it. The 0.7.0 release carries a prebuilt okf-render archive for each of Windows, Linux and macOS, on x64 and arm64, next to a checksums.txt. On Linux and macOS the install script fetches the right one, checks its SHA-256 and puts it on your PATH:

curl -sSL https://raw.githubusercontent.com/jchable/okf4net/main/packaging/install.sh | sh -s -- --bin okf-render

On Windows, download the okf-render-0.7.0-win-x64.zip (or win-arm64) asset from the release page and unzip it. The okf-render winget package has been submitted and is waiting in the winget-pkgs moderation queue, so winget install Coderise.OKF4net.Render does not resolve yet. If you would rather build it, the dotnet run command at the end of this post needs only the .NET SDK 10.0 or later.

In short: one command, one folder, index.html opened from disk. Prebuilt archives are on the 0.7.0 release; the install script covers Linux and macOS.

A guided tour

All the captures below are of acme_retail (nine concepts) or of a synthetic bundle of 112 concepts that the screenshot script generates, with fictional names, to show what nine concepts cannot.

The concept page

Concept pages and the index share one header: the bundle's name with its concept and link counts, the Jump to a concept… button, Filters, Global graph and the theme toggle (the graph page has the same header, with Reading view in place of Filters). Below it, three columns from 1,100 px of window width up:

On the left, the explorer, described below.
In the middle, the concept. A breadcrumb, the title, and chips for the type, the status, the trust tier with who verified the concept and when, and its staleness. The frontmatter box shows four entries the chips do not already show, with Show all for the rest. Then the body, rendered in the browser through a sanitizer (more on that below), with broken links flagged and heading anchors that make an author's own #usage links land.
On the right, the context. On this page lists the headings and marks the one you are reading, Neighbourhood draws the concept's links, and Referenced by lists the concepts that link to this one.

The explorer

The explorer lists the bundle the way its directories do. A concept that is also a folder (foo.md beside foo/) can be opened and expanded separately. Rows show the last segment of the id, with the title as a tooltip.

Types are shapes, not only colours. The types are ranked by how many concepts carry them. The five most frequent get a circle, a square, a diamond, a triangle and a ring, each with its own colour; every further type shares a sixth shape. The same shape stands for the type in the explorer, the palette, the chips, the lists and both graphs. The type chips filter the tree: press several to show any of them, then narrow by name.

Trust and staleness come from the concept's own frontmatter. A filled dot marks a human-reviewed concept: its verified field (§5.2) holds at least one stamp by a human:<id> actor. A ring marks a machine-confirmed one: stamps, none by a human. No verified key, no mark. The tiers come from the same audit code okf audit runs. An hourglass marks a concept past its stale_after date, judged as of reading: the page compares it with your browser's clock when it opens and when the tab comes back to the foreground, so a site rendered in March can show a concept as stale in June.

A trust mark is a declaration, not a proof: it shows who a concept says reviewed it. The spec calls these tiers advisory signals, not access control.

Jump to a concept

Press Ctrl+K or / on any page, or click the button, and type. The palette matches what you type against concept titles, ids and tags, using fixed tiers tried best first: an exact id, then a prefix of the title or id, then a substring of either, then an exact tag. Ties keep the bundle's order. There are no weights, and it never reads a concept's body.

Why there is no full-text search. OKF4net has exactly one full-text scorer, ConceptSearch, in the .NET library, shared by the agent tools and the catalog so that "search" means one thing everywhere. A static site has no process to run it in, and copying its weights into JavaScript would create a second scorer that drifts from the first. So the palette navigates; it does not search. Body search exists today through the library and the okf-mcp server, and interactive browsing with search is planned as a VS Code extension (#163). There is no okf serve, and none is planned.

The Neighbourhood

A concept page whose concept has neighbours (links out or links in) gets a Neighbourhood section: the concept in the middle, its neighbours around it in rings, at 1 hop or, with the button, 2 hops; the legend reads solid = links to, dashed = referenced by. A link to a concept that does not exist is drawn as a ghost that never navigates. Open in graph opens the global graph on this concept.

The panel draws at most 40 nodes, the concept included, direct neighbours first, and says +N omitted beyond. At the cap it is crowded. Here is the hub of the synthetic bundle, a glossary term with 61 neighbours:

Two things make it usable anyway. Under the drawing, List gives every neighbour, drawn or not, with its relation to the concept (links to, referenced by, or two hops via which neighbour). And Enlarge the neighbourhood, the icon beside the hop toggle, opens the same graph in a dialog of up to 1,100 × 760 px, with the list beside it:

Shapes and text keep their size; the rings spread out, and in a drawing this wide labels are cut at 32 characters instead of 20.

The global graph

Global graph in the header opens graph.html, which draws every body link of the bundle, the same edge set okf graph exports, with arrows pointing at the target.

Facets narrow what is drawn: type, trust, freshness (Stale only, as of now) and tags, and between facets, or inside one. Unmatched concepts are hidden or, as here, dimmed.
The drawing pans, zooms and lets you drag a node; Fit frames everything drawn.
The drawer shows the selected concept: chips, description, what it links to, what references it, and Open page.
Addresses. Selecting a concept writes graph.html#<concept id> to the address bar without adding a history entry, and opening such an address selects it, so you can paste it into a chat. A concept page's Global graph link uses it to land on that concept.

The layout is a force simulation computed in your browser. Here it is on the 112 concepts of the synthetic bundle:

Above 1,500 visible nodes (concepts and absent targets), the page does not draw at all: it shows the list and asks for narrower filters.

The side column, the theme and small screens

The right-hand column (the context panel, or the graph's drawer) has a splitter. Drag it with a mouse, a finger or a pen, or focus it and use the arrow keys (16 px a step, 64 with Shift, Enter to reset). The width stays between 240 and 720 px, never leaving the middle column less than 360, and is remembered in the browser's local storage. The global graph refits to its new canvas unless you have moved the view yourself.

The pages follow your system's light or dark setting; the moon button overrides it and remembers the choice where the browser allows storage.

Below 1,100 px the columns stack (the page first, then its context, then the explorer), and on a phone the header wraps:

In short: an explorer with type shapes and trust marks, a palette that jumps by title, id or tag, a Neighbourhood per concept with a dialog when it gets crowded, a global graph with facets, a drawer and shareable addresses, and a layout that holds from a phone to a wide screen.

Accessibility and the keyboard

We treated "a graph is a picture" as the main accessibility risk and designed around it.

One tab stop, then the arrows. The global graph's drawing is a single tab stop. Inside it, Page Up and Page Down walk the nodes in the bundle's order, so an isolated node or a separate component is always reachable; Home and End go to the first and the last; an arrow key goes to the nearest neighbour in that direction; Space selects and Enter opens the concept's page. The selected node carries aria-current.

A text equivalent for every drawing. The Neighbourhood has its List. The global graph has its List, which replaces the drawing in place and honours the same facets, plus the detail drawer:

Focus is handled in dialogs. The palette is a modal dialog: focus goes to its field, stays inside, and returns to where it was on Esc. In the enlarged Neighbourhood, Tab wraps round the dialog's own controls, the page behind is inert and does not scroll, and Esc, Close or a click on the backdrop return the focus to the button that opened it.

Never colour alone. Types differ by shape and colour, trust by a filled dot or a ring. Text targets 4.5:1 contrast and shapes 3:1, in both themes, measured in real browsers. Under reduced motion, the graph's layout still runs, but only its start and end are drawn.

What we have not done yet: manual checks with an input method editor and with a screen reader. They are tracked in #177.

In short: one tab stop and arrow-key navigation in the graph, a list for every drawing, real focus management in both dialogs, shapes as well as colours. IME and screen-reader checks are still to do.

Under the hood

This part is for the engineers.

What "zero dependency" means here

OKF4net allows no third-party runtime dependency per project, and OKF4net.Viewer, the library behind okf-render, references only the core library. There is no npm package and no bundler: the browser scripts are plain files embedded in the .NET assembly. Two things are vendored, as named exceptions: marked v15.0.12 (MIT), and the Inter, Inter Tight and Space Mono fonts (SIL OFL 1.1). Their licence texts are written into every generated site and ship beside the binary. okf never references any of it.

One generated data file, classic scripts

The interactive parts need the whole bundle on every page: the tree, every concept's title, type, tags, trust tier and deadline, every edge. okf-render writes it once as assets/okf-index.js, a script that sets window.OKF_INDEX, because a fetch of a local JSON file is blocked under file://. For the same reason the scripts are classic scripts, not ES modules: each one is wrapped in its own function, exposes one global, and does nothing if what it needs is missing, which also lets the Node test harness load each one exactly as a page does.

Bundle text is untrusted and ends up in a JavaScript file, so every string from the bundle goes through one C# quoting function that writes a JSON string literal and also escapes <, >, &, U+2028 and U+2029. The index holds only arrays and fixed-key records, never an object keyed by concept id: __proto__, constructor and toString are valid concept ids, and an object literal keyed by one of them does not mean what JSON.parse of the same text means. Measured during development on OKF4net's own generated bundle (795 concepts, 912 edges), the file was 407,325 bytes.

A layout that is the same everywhere

A force layout usually starts from random positions and runs until it looks settled, so two people opening the same bundle see two different pictures. We wanted the same picture, so the simulation, okf-sim.js, is a pure module with constraints written at its top:

no DOM, no clock, no Math.random;
only + - * / % >>>, Math.sqrt (whose rounding ECMAScript fixes) and the exact Math.floor, ceil, trunc, abs, min, max and imul; never sin, cos, exp, pow or **, whose results the standard lets each engine approximate;
a fixed order for every accumulation;
work counted, never timed, spread over animation frames: a frame may stop mid-iteration, but positions only change when an iteration completes, so the state after k iterations does not depend on the slicing.

The starting positions are a grid in index order, jittered by an integer generator seeded from the node and edge counts:

// 32-bit linear congruential generator on an integer state: exact.
function nextState(state) {
  return (Math.imul(state, 1664525) + 1013904223) >>> 0;
}
// ... in initialLayout(n, edgeCount):
var state = (Math.imul(n, 73856093) + Math.imul(edgeCount + 1, 19349663)) >>> 0;

Labels are part of the layout: each node gives the box its shape and label cover, with the label width estimated from its length rather than measured, because measured text differs between browsers and would make the layout differ too. The result: the same positions, bit for bit, in Chromium, Firefox and WebKit, checked on acme_retail, on the harness fixture, on OKF4net's own bundle and on a synthetic bundle of 1,414 nodes.

The sanitizer is the whole defence

A bundle's markdown is untrusted input. marked turns it into HTML in the browser, and viewer.js then sanitizes the parsed DOM: an element allowlist, a per-tag attribute allowlist that drops every on* handler, URL-scheme checks on href and src, and opaque elements (<script>, <style>, <iframe> and a few more) removed with their content. Other unknown elements, such as <details>, are unwrapped: the element goes, its sanitized children stay.

An earlier version also patched marked's renderer hooks to drop raw HTML. Measured against the harness's hostile payloads, it stopped nothing the DOM sanitizer did not already stop, and it deleted benign content: a <details> block with a summary and some text came out empty. It also could not see the case the DOM sanitizer exists for: marked's Renderer.image() writes the alt attribute without escaping it, so a plain markdown image, ![foo" onerror="alert(1)](x.png), with no raw HTML anywhere, breaks out of the attribute. Only a defence that looks at the resulting DOM catches that, so the hooks were removed.

The `class` attribute problem

The sanitizer keeps class in one place only: on <code>, where marked writes a fenced block's language-… class. But it means a concept body can contain <code class="okf-chip">, wearing the viewer's own class names. If the stylesheet styled .okf-chip wherever it appears, a hostile concept could draw a fake human-reviewed badge, hide text from sighted readers, or lay an overlay that looks like a dialog.

So every rule for the viewer's own interface, its chrome, is anchored to a container body content cannot produce, such as #okf-explorer or body > header.bar (the sanitizer strips id from the body), and every lookup of the viewer's own elements starts from a fixed element id or an anchored selector, with any descendant query by class kept inside that root, so a class name worn by body content is never searched for from the whole document. The one lookup that does start from the whole document, resolving a #fragment to a heading, checks that the element it finds is inside the page body before using it. The harness enforces it in three layers, none claimed as a proof on its own: a static scan of every selector in the stylesheet; a selector-matching comparison between a body element wearing each chrome class and its unclassed twin; and a comparison of their computed styles. Each delivery slice adds a fixture page listing its chrome classes, so new chrome is covered as soon as it exists.

Testing code that xunit cannot run

The .NET test suite cannot execute JavaScript, and a test that greps a .js file for a marker string stays green when the code behind the marker is gutted. So the guarantees live elsewhere:

A jsdom harness (tools/viewer-security-check/) loads the real marked.min.js and every viewer script into a site generated by the real okf-render from a hostile fixture bundle: titles containing HTML, concepts named __proto__, constructor and toString, broken links, clobbering attempts, body code wearing chrome classes. It drives the layout through an injected scheduler, so its checks are deterministic. It runs in CI as the viewer sanitizer (JS) job, with 453 cases at the time of writing.
Mutation checks. For the newest parts, deliberate bugs were planted in the scripts to check that a case fails for each: the splitter's cases killed 50 such mutants, the enlarged dialog's 30.
A tooled recette in real browsers, run by hand: it opens the generated sites from file:// in Chrome, Edge, Firefox and WebKit and measures what jsdom cannot see, such as fonts actually loaded, contrast in both themes, layout at three widths, and that no request leaves the site. Playwright is resolved at run time, never a dependency.
A Native AOT smoke test in CI publishes the native okf-render on Linux, macOS and Windows, renders a bundle, checks the output, and executes the okf-index.js the native binary wrote.

The honest limits

The 40-node cap is crowded at the cap. On a hub, some labels sit far from their node and the edges converge on the centre. The dialog and the list are the answer, not the panel drawing.
Big graphs. Above 1,500 visible nodes the global graph shows a list instead of a drawing. The palette scans every concept on each keystroke, which very large bundles will feel.
Not checked by hand yet: input method editors and screen readers (#177), and Safari: the recette runs WebKit, which is not Safari.
No full-text search, by design (see above), and no live reload: the site is a snapshot, so render again after the bundle changes.

In short: no new runtime dependency, one generated index, classic scripts for file://, a layout made deterministic by construction, a DOM sanitizer that does the whole job, anchored chrome selectors, and tests that run the real JavaScript. The limits are listed rather than hidden.

How it was built

The viewer was specified before it was written: a design document in the repository (docs/superpowers/specs/2026-10-06-okf-viewer-interactive-design.md, fifteen revisions) with validated mockups and the owner's decisions. It was delivered in slices on one branch (navigation, fidelity to the mockups, the local graph, the global graph, then the splitter and the enlarged dialog), each with its own plan, harness cases and browser recette. It was reviewed task by task and checked in real browsers, not only by the harness.

Those browser checks earned their place, because jsdom does no layout. Labels overlapped on the first open of the global graph, which is why the simulation now lays out boxes, not points. A CSS rule pushed the selected list entry a screen below the fold, in Firefox only. The graph page held the main thread too long near the node limit until its drawing was spread over frames.

In short: a written spec, small slices, and a browser in the loop for every slice.

Also in 0.7.0

The viewer is the headline, but the release has more.

`okf` as a dotnet tool

okf has been a Native AOT binary so far (winget, an install script, release archives). That still works, and still needs no .NET runtime. New in 0.7.0: a repository that already builds with the .NET SDK can pin okf the way it pins any other tool, which suits CI better than downloading a binary:

dotnet new tool-manifest          # once, in the repository; commit the dotnet-tools.json it creates
dotnet tool install OKF4net.Cli   # records the version in the manifest
dotnet tool restore               # what CI runs
dotnet okf validate ./knowledge

dotnet tool install -g OKF4net.Cli installs it for your own shell, and dnx OKF4net.Cli --yes validate ./knowledge runs it once with nothing installed. okf validate exits 1 on a non-conformant bundle, so the step fails the build; warnings are reported and never fail it. The package is portable IL and needs the .NET 10 runtime or a later one. A new CI job packs it, restores it from a manifest in a fresh directory and asserts okf validate's exit code on a conformant and on a non-conformant bundle, because the in-process tests never see the package itself.

A hardening wave

Four fixes in 0.7.0 close ways to crash, hang or fool the library:

okf verify could be made to print a forged line. The (replaces …) suffix echoed the timestamp already stored in a concept without escaping it, so a line break in that value printed a fake recorded … line. That mattered because okf verify and the okf_verify agent tool feed lines to people and to models. Every value on those lines is now made line-safe by the renderer itself (#123).
A value built in code could crash or hang the library. A YAML mapping can hold itself, or hold the same sub-mapping at every one of 60 levels. Hashing such a value, comparing two of them or printing one used to overflow the stack, run out of memory or never finish. They now answer, or refuse with a normal exception (#158, #189). Nothing the parser returns is affected.
Loading a bundle with a very popular concept was quadratic. A concept cited by 100,000 others took about 170 seconds to build its backlinks; it now takes under one second, and the order of the results is unchanged (#148).
A junction or symlink to a bundle now shares the bundle's write lock, so two writers in one process reaching the same bundle by two paths can no longer interleave and lose an update (#86). The lock is still in-process only: a second process writing the same bundle is not serialized against.

What to check when you upgrade

Frontmatter.RequiredKeys and Frontmatter.RecommendedFields are read-only IReadOnlyList<string> properties instead of mutable arrays (#113): compiled references to the old fields break, and so do .Length and element assignment.
The YAML subset has one nesting rule, at most 1000 nested collections, for block and flow alike. Block documents nested 501 to 1000 deep now load. Documents that mix block and flow past 1000 in total, which used to load, are now rejected. Real frontmatter is a handful of levels deep.
A bare okf or okf-render prints its usage on stdout and exits 0, like --help; it used to use stderr and exit 1. A verb missing a required argument still fails.
The YAML emitter refuses, with a YamlEmitException, a value built in code that reuses collections or long strings past a 16 MiB budget, or whose text would pass 256 MiB. Everything the parser returns is unaffected.

The full list is in the changelog.

Try it, and where to help

git clone --branch v0.7.0 --depth 1 https://github.com/jchable/okf4net && cd okf4net
dotnet run -c Release --project src/OKF4net.Render -- bundles/acme_retail --out ./acme-site
# open ./acme-site/index.html

That needs only the .NET SDK 10.0 or later. With the prebuilt okf-render from the section above, the second line becomes okf-render bundles/acme_retail --out ./acme-site.

Then point it at your own bundle. If you do not have one, okf can validate one you write by hand, and the getting-started guide walks through it.

OKF4net is a small project and contributions are welcome:

good first issue: each one names the files to touch and the test to make pass.
help wanted: bigger pieces.
Viewer-specific help we would value: a screen-reader and IME pass (#177), a check in real Safari, and measurements on large real-world bundles.
Questions before you code: GitHub Discussions. How to build, test and submit: CONTRIBUTING.md.

The full viewer guide is on the project site.

Summary

What you get	Where
A static site you open from disk, no server, no network	`okf-render <bundle> --out <dir>`, then `index.html`
Tree explorer with type shapes, type filters, trust and staleness marks	concept pages and the index, left column
Jump to palette over titles, ids and tags (not full-text search)	every page: Ctrl+K or /
Concept page: chips, folding frontmatter, sanitized body, contents, Referenced by	every concept page
Neighbourhood at 1 or 2 hops, 40-node cap, full list, enlarge into a dialog	concept page, right column
Global graph: deterministic layout, facets, drawer, list, keyboard, `#<concept id>` addresses	`graph.html`
Resizable side column, light and dark themes, phone layout	everywhere

Try it: prebuilt archives are on the 0.7.0 release, install.sh --bin okf-render installs one on Linux and macOS, and dotnet run --project src/OKF4net.Render builds it from the tag.
Also in 0.7.0: okf as the OKF4net.Cli dotnet tool for CI; fixes for a forged okf verify line, crashes and hangs on values built in code, and a quadratic backlink build; four changes to check when you upgrade.
Limits and next: no full-text search in the site (search is planned in the VS Code extension, #163); IME, screen-reader and Safari checks to do (#177 for the first two); a list instead of a drawing above 1,500 nodes.
Contribute: good first issues, Discussions, the repository.

OKF is an open format from Google; OKF4net is an independent .NET implementation of it, LGPL-3.0-or-later. If the viewer is useful to you, or broken for you, we would like to hear about it.

OKF4net 0.6.0: auditing what your AI agent knows, in zero-dependency .NET

Julien Chable — Thu, 01 Oct 2026 13:26:57 +0000

OKF4net 0.6.0 shipped on 1 October. This post covers what it does and what
changed, with commands you can run.

What OKF4net is

The Open Knowledge Format
(OKF) is Google's open format for knowledge an AI agent can read: a directory
of markdown files, each with YAML frontmatter saying what the file is, where it
came from and how far to trust it. No database, no server. You ship it with
git clone.

OKF4net is an independent .NET 10
implementation of OKF v0.2. The core library and the okf CLI use the base
class library only: the YAML-subset parser, the markdown link scanner and the
argument parser are all in the repository. The CLI is published as a Native AOT
binary.

The problem 0.6.0 goes after

Once an agent reads from a knowledge bundle, the question stops being "is this
file valid?" and becomes "should anyone believe it?". A concept may be
well-formed and two years out of date. It may have been written by a model and
never read by a person.

OKF v0.2 has fields for this: who generated a concept, who verified it, when it
goes stale. 0.6.0 adds the tooling to query and maintain them.

`okf audit`: ask the whole bundle

okf audit bundles/acme_retail --stale --trust unverified,machine-confirmed

This lists the concepts that are past their stale_after date and that no
human has confirmed. With no flags, okf audit gives you the staleness
worklist. It exits 0 and prints nothing when there is nothing to do, so it
drops into a CI job or a pipe.

`okf verify`: record a review

okf verify bundles/acme_retail metrics/revenue --by human:ada

This writes a dated verification stamp into the concept's frontmatter. It reads
ids from stdin too, so the two verbs compose:

okf audit bundles/acme_retail --trust unverified | cut -d' ' -f1 \
  | okf verify bundles/acme_retail --by human:ada -

One caveat, stated in the README as well: the stamp is a dated declaration. The
tool cannot authenticate the name you pass to --by.

`okf-render`: a browsable site from a bundle

okf-render bundles/ga4 --out ./ga4-site

The output is static HTML you can open from disk or host anywhere. It is a
separate binary from okf so that the validator people run in CI stays small.

Because the viewer renders untrusted markdown in a browser, it sanitizes the
parsed DOM against an element and attribute allowlist. That sanitizer is tested
by a Node harness that runs the real viewer code against hostile payloads in CI.
We added the harness after finding that two .NET tests "proving" raw HTML was
disabled were green while the sanitizer had a hole: they were reading the .js
file as text, because xunit cannot execute JavaScript.

Attested computation, in a real container

OKF §10 lets a concept declare a computation (a script or SQL) and an attester
script that judges the result. OKF4net.Attestation.Containers runs both in
Docker, Podman or nerdctl:

the bundle's own script runs, not a C# port of it;
containers run as an unprivileged user, all capabilities dropped;
no volume is mounted, every payload travels over stdin;
SQL parameters are bound by the database driver, never spliced into the text.

It is in the repository with a worked sample, but not published to NuGet yet,
since it needs a container engine on the machine.

For agent builders: MCP, read-only by default

dotnet tool install -g OKF4net.Mcp

okf-mcp exposes a bundle to any MCP client over stdio. As of 0.6.0 it serves
the bundle read-only; set OKF_MCP_WRITABLE=1 to register the write tools.
There are 13 okf_* tools in total, including the new okf_audit and
okf_verify.

The numbers

	0.5.0 (31 Jul)	0.6.0 (1 Oct)
Commits in the release	93	642
Lines of C# in `src/`	13,439	24,120
Lines of C# in tests	13,418	30,512
Tests run	912	2,352
Projects under `src/`	7	10

The project is ten weeks old and 1,194 commits in. In this release the test
code overtook the product code, which is a fair summary of where the effort
went.

Upgrading from 0.5.0

0.6.0 has breaking changes. The four you are most likely to meet:

Bare attester.resource and computation paths resolve from the bundle root (§6.2). Run okf validate; it tells you what to rewrite.
The frontmatter fence must be --- at column 0, and YAML anchors, aliases and tags are rejected with a named error.
Bundle.ReadResourceText throws for a path outside the bundle root.
okf-mcp no longer writes unless you opt in.

The full list is at the top of the
0.6.0 changelog section.

Get it, or get involved

dotnet add package OKF4net

Binaries for Windows, Linux and macOS are on the
release page, and the
docs are at jchable.github.io/okf4net.

The project is looking for contributors. There are issues labelled
good first issue
and a public roadmap.
If you run Podman or nerdctl, trying the container runtime on it would be a
real contribution: so far it has only been exercised on Docker.

Agent memory you can 'git blame' and how OKF4net grew into a zero-dependency .NET toolkit

Julien Chable — Fri, 04 Sep 2026 05:51:01 +0000

Most answers to "give my AI agent long-term memory" hand you an opaque vector store: embeddings in a database you can't read, can't diff, and can't easily redact. I wanted the opposite : memory I can open in an editor, review in a pull request, and 'git blame' line by line. That itch is what pushed OKF4net from a single library into a small toolkit over the last few months. It just reached v0.5, and this post is about what's new — starting with the part I'm most excited about.

If you haven't seen it before: OKF4net (docs & project site) is an independent, zero-dependency .NET implementation of Google's Open Knowledge Format (OKF). OKF represents knowledge as a directory of markdown files with YAML frontmatter, cross-linked like a wiki, versioned in git. No database, no proprietary format: if you can 'cat' a file you can read it, if you can 'git clone' a repo you can ship it.

The headline: agent memory as plain markdown

'OKF4net.Agents' turns a bundle into tools and context for the Microsoft Agent Framework. 'OkfBundleTools' exposes read, browse, graph, search, write, append-log, validate and more as function tools an agent can call directly. Layer 'OkfContextProvider' onto the same instance and the agent automatically gets relevant bundle context injected into each turn — and, when you opt in, its exchanges captured back into the bundle as long-term memory:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OKF4net.Agents;

var tools = new OkfBundleTools("./my_bundle");

// Memory capture is opt-in (Disabled by default) — turn it on explicitly.
var provider = new OkfContextProvider(
    tools,
    new OkfContextProviderOptions { MemoryCapture = MemoryCaptureMode.Enabled });

AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    ChatOptions = new ChatOptions { Tools = tools.GetTools() },
    AIContextProviders = [provider],
});

var response = await agent.RunAsync("What do we know about orders?");

Here's what makes it different. Capture is deterministic (no extra LLM call): after each turn, the last user message and the agent's final response are appended to a single memory concept for the day ('memory/'), with a matching 'log.md' change-history entry. Those writes go through the exact same validated, lock-protected, path-safe write path any other caller uses, and the captured text is blockquote-neutralized so a payload smuggled into a message can't fake document structure.

The payoff is that memory is just files in your bundle. You can:

'git blame' a remembered fact to see exactly when and in which exchange it entered the memory,
diff memory across commits and redact a line with a normal edit,
point a second agent at the same directory with no export step,
and review the whole thing in a PR like any other change.

I'll be honest about where v1 stands: this captured memory is bundle-global, unscoped, and opt-in : it carries no session/user/tenant key, so it's meant for a shared, non-sensitive knowledge base, which is exactly why it ships disabled by default. If you need per-caller isolation, that lives one layer up in the catalog (below). I'd rather ship an honest, inspectable v1 than a magic box (maybe next version ?).

The rest of what's new (v0.2 → v0.5)

The memory story is the headline, but the project grew in every direction since the first release. OKF4net now ships as five NuGet packages plus a couple of standalone tools:

A local MCP server, 'OKF4net.Mcp'. The 'okf-mcp' 'dotnet tool' exposes a bundle to Claude Desktop or Claude Code over the Model Context Protocol now with bundle auto-discovery, so it finds your knowledge base instead of making you wire a path. Recipes for other MCP-capable editors (VS Code, Cursor, Rider…) are on the issue tracker as good-first contributions.
A multi-bundle catalog, 'OKF4net.Catalog'. A 'catalog.json' manifest, a source resolver, and full-text search across many bundles with read-only knowledge sources and writable memory tiers ('session' / 'user' / 'tenant') for exactly the per-caller scoping the agent provider's v1 memory doesn't do.
Machine-readable CLI output. The Native AOT 'okf' CLI ('validate'/'info'/'index'/'graph'/'parse'/'fmt') gained a '--json' flag on 'validate' and 'info', so a CI step can parse structured diagnostics instead of scraping text.
A producer that turns a repo into a bundle. 'producers/OkfProducer' generates a validated OKF bundle straight from an existing repository (npm/NuGet/README detection so far). It's an early walking skeleton, but it closes the loop: you don't have to hand-author a bundle to try the ecosystem.

Through all of it, the core constraint held: 'OKF4net' and its CLI have zero third-party runtime dependencies — base class library only, hand-written YAML-subset parser and link scanner included. That's what lets the CLI ship as a single self-contained Native AOT binary with no runtime to install, and it keeps the barrier to contributing low: there's no framework to learn before you can read the code. Much of OKF4net is built with AI assistance (Claude Code), with the OKF spec and an extensive test suite — including byte-exact golden CLI captures — as the ground truth every change has to satisfy.

Come contribute

OKF4net is open source under LGPL-3.0-or-later and deliberately welcoming to first contributions, no prior OKF knowledge needed. The 'good first issue' label names the files to touch and the test that should go green, 'ROADMAP.md' shows where it's headed, and Discussions is the place to ask before you write any code. If you'd rather start by reading, the project site and docs are the friendlier way in. Your first PR is three commands away: 'dotnet build', 'dotnet test', 'dotnet format'.

If "agents that remember things in files you can read" sounds useful, I'd love the help and the feedback.

OKF4net is built and maintained by Coderise.

I ported a knowledge-format (OKF) library to zero-dependency .NET — here's what I learned

Julien Chable — Mon, 27 Jul 2026 10:09:05 +0000

If you can cat a file, you can read the knowledge base. If you can git clone a repo, you can ship it. No vector database to stand up, no proprietary export format, no vendor lock-in — just a directory of markdown files with YAML frontmatter that a human can open in any editor and an agent can read with ReadFile. That's the whole pitch, and it's the reason I spent the last few weeks porting a library to C# to get it onto .NET.

The format behind that pitch is Google's Open Knowledge Format (OKF) v0.2, and the library is OKF4net (docs & project site) — a zero-dependency .NET
(C#, net10.0) implementation, plus an optional layer for wiring OKF bundles straight into agents built on the Microsoft Agent Framework. This post is the launch story: what OKF actually is, why I ported it instead of writing a wrapper, and what "zero dependency" really costs and buys you.

What OKF is

OKF defines a bundle: a directory tree of UTF-8 markdown files, where each file is a concept — a YAML frontmatter block followed by a markdown body. Concepts cross-link each other with ordinary markdown links, index.md files give you progressive-disclosure directory listings, and log.md files record date-grouped change history. The only hard conformance requirement is a non-empty type field on every concept; everything else — unknown types, unknown keys, broken links — has to be tolerated by a conformant consumer. It's deliberately boring as a format, which is the point: the format is context here, not the pitch. The pitch is what you get to do with plain files — diff them, review them in a PR, grep them, back them up with nothing but git.

The port story

This repository used to ship a Rust implementation of OKF. I removed it at commit d20343c — but only after proving, file by file and command by command, that the C# port produced byte-identical output. tests/fixtures/golden/ holds five golden captures taken directly from the Rust binary's stdout — validate, info, graph --dot, fmt, and index — against a shared example bundle, and the C# CLI is diffed byte-for-byte against every one of them in CI. As of today the full suite passes end-to-end, including five byte-exact golden CLI comparisons against the original captures.

I'll say the quiet part out loud: this port was AI-assisted, done largely with Claude Code driving the migration file by file, spec section by spec section, with the golden fixtures as the ground truth it had to match exactly. I think that's worth stating plainly rather than glossing over — a byte-exact port across languages is a fairly mechanical, well-specified translation task with an unambiguous pass/fail signal (does the output match the captured bytes, yes or no), which is exactly the kind of task where an AI pair-programmer earns its keep and where you can trust the result because you can verify it byte-for-byte rather than having to take anyone's word for it. The interesting design decisions — the YAML subset, the permissive-loading philosophy, the two-tier validation split — came from following the spec and the Python reference implementation; the AI assistance was in the grinding, get-every-byte-right execution, not the architecture.

Show, don't tell

Here's the library, loading a bundle and running a conformance check:

using OKF4net;

var bundle = Bundle.Load("./my_bundle");
Console.WriteLine($"{bundle.Count} concepts");

// Conformance check (§9).
var report = BundleValidator.Validate(bundle);
if (report.IsConformant)
{
    Console.WriteLine($"conformant with OKF v{OkfSpec.Version}");
}

// Traverse the cross-link graph.
var id = ConceptId.Parse("tables/orders");
foreach (var link in bundle.LinksFrom(id))
{
    Console.WriteLine($"{id} -> {link.Target} (exists: {link.Exists})");
}

Bundle.Load never aborts on a malformed concept file — it collects parse failures into bundle.ParseErrors and keeps walking the tree, because a knowledge base that one bad file can take down entirely is a bad knowledge base.

And here's the CLI, which is the same tool the Rust binary used to be, invocation-for-invocation:

okf validate ./bundles/ga4
okf graph ./bundles/ga4 --dot | dot -Tsvg > graph.svg

okf validate exits non-zero on a non-conformant bundle, so it drops straight into a CI step. The CLI ships as a self-contained, Native AOT single-file binary — no .NET runtime install required on the machine that runs it.

The agents angle

The reason I care about this format enough to port a whole library for it is OKF4net.Agents, which turns an OKF bundle into tools and context for the Microsoft Agent Framework. OkfBundleTools wraps one bundle root and exposes nine function tools — read, browse, graph, search, write, append-log, regenerate-indexes, validate, changes-since — that an AIAgent can call directly:

var tools = new OkfBundleTools("./my_bundle");
AIAgent agent = chatClient.AsAIAgent(tools: tools.GetTools());
var response = await agent.RunAsync("Search the bundle for concepts about refunds.");

Layer OkfContextProvider onto the same tools instance and, opted in explicitly, an agent's exchanges get captured as long-term memory — one markdown concept per UTC day, written through the same validated, lock-protected write path the tools use, plus a matching log.md entry. That's the part I think is genuinely different from the usual answer to "give my agent memory": instead of an opaque vector store you can't audit, memory is a markdown file in a git-tracked directory. You can open it, diff it across commits, redact a line, or point a second agent at the exact same directory with no export step. It's not a fit for every use case — the README is upfront that v1 memory is bundle-global and unscoped, so it's opt-in and meant for a shared, non-sensitive bundle rather than a multi-tenant deployment — but for a single team's shared knowledge base, "memory you can git blame" is a real capability, not a slogan.

Design choices

The whole library — OKF4net and OKF4net.Cli — has zero third-party runtime dependencies: no YAML library, no CLI-parsing package, nothing. It has its own documented YAML subset parser (frontmatter is scalars, lists, and shallow maps — no anchors, no tags, no multi-document files, and it says so with a clear error if you hand it those), its own markdown link scanner, and its own argument parsing, all on top of the .NET base class library. That constraint is what makes the CLI publishable as a single-file Native AOT binary with no runtime to install, and it's what keeps the barrier to contributing low — there's no framework to learn before you can read the code. OKF4net.Agents is the one exception, since talking to Microsoft.Agents.AI requires depending on it; everything else stays dependency-free by design, enforced project by project. The project also ships OKF4net.Catalog, a local multi-bundle catalog with search-by-source resolution, and OKF4net.Mcp, an MCP server that plugs a bundle straight into Claude Desktop or Claude Code — so agents and tools have a ready path to discover and query bundles without writing that plumbing themselves.

Come contribute

OKF4net is young and I'd rather it stay welcoming than gate-kept. If you'd like to start by reading, the project site and docs are the friendlier entry point — a guided overview and getting-started walkthroughs.
You don't need any prior OKF knowledge to help — the good first issue label names the files to touch and the test that should go green when you're done, ROADMAP.md lays out where the project is headed, and Discussions is the place to ask a question before you write any code. The project is licensed LGPL-3.0-or-later, and the bar to your first PR is exactly three commands: dotnet build, dotnet test, dotnet format. If any part of "knowledge bundles you can cat and agents that remember things in files you can read" sounds useful to you, I'd love the help — and the feedback.

DEV Community: Julien Chable

A folder of markdown you can actually browse: OKF4net 0.7 and the interactive okf-render

The problem: easy to diff, hard to browse

One command, a folder of files

A guided tour

The concept page

The explorer

Jump to a concept

The Neighbourhood

The global graph

The side column, the theme and small screens

Accessibility and the keyboard

Under the hood

What "zero dependency" means here

One generated data file, classic scripts

A layout that is the same everywhere

The sanitizer is the whole defence

The class attribute problem

Testing code that xunit cannot run

The honest limits

How it was built

Also in 0.7.0

okf as a dotnet tool

A hardening wave

What to check when you upgrade

Try it, and where to help

Summary

OKF4net 0.6.0: auditing what your AI agent knows, in zero-dependency .NET

What OKF4net is

The problem 0.6.0 goes after

okf audit: ask the whole bundle

okf verify: record a review

okf-render: a browsable site from a bundle

Attested computation, in a real container

For agent builders: MCP, read-only by default

The numbers

Upgrading from 0.5.0

Get it, or get involved

Agent memory you can 'git blame' and how OKF4net grew into a zero-dependency .NET toolkit

The headline: agent memory as plain markdown

The rest of what's new (v0.2 → v0.5)

Come contribute

I ported a knowledge-format (OKF) library to zero-dependency .NET — here's what I learned

What OKF is

The port story

Show, don't tell

The agents angle

Design choices

Come contribute

The `class` attribute problem

`okf` as a dotnet tool

`okf audit`: ask the whole bundle

`okf verify`: record a review

`okf-render`: a browsable site from a bundle