Research wiki 2 — OKF for a machine-maintained wiki
Agents maintain this audio ML wiki on a server. OKF as the file contract — typed pages, path-as-ID, plain links, per-dir indexes — plus a local schema so the map stays readable and diffable.
Notes from a research desk I built to teach myself audio ML — get signal, find relevant data, and answer questions from a compounding LLM wiki kept as plain files under OKF.
Part 2 — after the jobs
Part 1 is how the desk runs: scheduled agents, a shared inbox, and a compounding wiki (sources/ / entities/ / concepts/).
This post is how those files stay durable — how the wiki evolved using Open Knowledge Format (OKF) as a reference, not as a product to implement.
Why a compounding wiki
A flat pile of summaries stops me losing papers. It does not compound.
The LLM wiki pattern (and Decoding AI’s writeup) is what Part 1 already shipped: compile once into interlinked markdown, revise concept and entity pages in place, lint the structure. Cross-source synthesis is written at ingest time. At read time I retrieve. I do not ask search to rebuild the map from raw files.
| Directory | Job |
|---|---|
sources/ | One page per ingest; newsletter/commentary pages often never reach the concept layer |
entities/ | Named models/datasets in 2+ sources (CLAP, MERT, MusicFM, …) |
concepts/ | Themes revised in place — synthesis, contradictions |
fulltext/ | GROBID extracts for Primary-topic arXiv (grounding input) |
| indexes + schema | Routing and rules agents read first |
An OKF knowledge bundle is just this directory. That shape is the product. The open question was which file conventions keep it shareable — readable by agents, diffable in git — without locking the corpus into one vault dialect.
Why OKF as reference
OKF is the checklist. Google’s pitch is blunt: the missing piece is a format, not another knowledge service. A knowledge bundle is a directory of markdown files with YAML frontmatter — readable by humans and agents, shippable as a folder, no required SDK or database.
I used it as a reference because this corpus is machine-maintained. Agents write and revise pages on a server while I learn audio ML over months.
Decoding AI puts it the same way: OKF “formalizes the LLM-wiki pattern into a portable, interoperable format.”
The conventions that mattered here:
type:in frontmatter — every content page declares what it is- Path-as-ID — the file path is the identity (
concepts/foo.md, not a vault UUID) - Plain markdown links —
[text](relative/path.md), not Obsidian[[wikilinks]] - Per-directory
index.md— routing next to the pages, not one global dialect
OKF does not prescribe my research taxonomy. WIKI-SCHEMA.md does that locally (which headings a concept must keep, when an entity earns a page). OKF is the portable file contract underneath.
Obsidian brackets are fine in a personal vault. Here the store has to stay readable with a dumb read, diffable in git, and traversable by lint scripts for years. That is what makes the map compound.
I was not “becoming OKF conformant.” I was checking which conventions we already matched and which ones were worth adopting.
Already aligned vs adopted
Lab pass on 2026-07-17 — 156 sources that day:
| OKF convention | This wiki |
|---|---|
Required type: frontmatter | Already on content pages |
| Path-as-ID / typed directories | Already — sources/, entities/, concepts/ |
| Plain markdown links (not vault wikilinks) | Adopted — relative [text](path.md); frontmatter holds plain relative paths |
| Per-directory indexes | Adopted — especially concepts/index.md |
Content pages were clean of unresolved [[wikilinks]] at cutover. Schema, log, and dated report artifacts were left alone on purpose — documentation and history. Occasional [[ on a later source page is schema drift for lint, not an unfinished migration.
What the format looks like
Domain titles in the live wiki are incidental here. Read the shape — frontmatter, paths, indexes, headings — not the audio ML prose.
Plain links (body)
A source page points at the concept layer with relative markdown (not [[wikilinks]]):
## Related
- [Concept title](../concepts/<slug>.md)
- [Another concept](../concepts/<other-slug>.md)Per-directory index
OKF’s optional index.md next to the pages. Live concepts/index.md is a routing list — one link per file, type tag on the line:
# Concepts Index
- [Title](<slug>.md) — concept
- [Title](<other-slug>.md) — concept
…New concepts currently append rather than re-sort. A generator quirk I have not chased — format still holds; sort order is local policy.
Typed page + local schema
OKF requires type: and treats the path as the ID. This wiki’s constitution (WIKI-SCHEMA.md) adds the body contract agents must keep. For type: concept: Synthesis revised in place, Contradictions kept explicit, plus Threads and Timeline — not a new summary file per paper.
Skeleton (fields and headings; body elided):
---
type: concept
title: "…"
last_updated: YYYY-MM-DD
related_entities:
- "../entities/<slug>.md"
related_concepts:
- "<slug>.md"
---
## Synthesis
… revised in place when new sources land …
## Contradictions
… disagreements kept live; never silently overwritten …
## Threads
…
## Timeline
…A live page fills that skeleton with field substance. The format win is that any agent (or cat) parses the same fields and headings without a vault dialect or a database.
Versioning the bundle
OKF-shaped knowledge is just files. Files belong in git.
The wiki sits in a private GitHub repo. A daily non-LLM sync commits and pushes changes — deterministic file work, kept outside agent cron. The same pass refreshes coding-agent pointers in AGENTS.md / CLAUDE.md toward index.md and WIKI-SCHEMA.md — an idea borrowed from LangChain OpenWiki, adapted to this layout rather than adopted wholesale.
Version the knowledge bundle with a boring trigger. Do not rely on an agent that “remembers to commit.”
When the checker lied
Validating the OKF move exposed a broken link-check. Orphan counts came back 125, then 124, then 1. Ground truth was 72.
Fix: pull the logic into check_links.py — a real script the lint skill calls, not an inline python3 -c inside markdown. Index listings stay routing; body links and frontmatter path refs both count.
Improvement: lint numbers are stable and comparable across runs, so a format change can be checked against a pre-change baseline instead of against a tool that lies.
Close
Not an OKF SPEC walkthrough. Part 1 built the living research wiki. This part made its shape a portable filesystem bundle — plain links, typed dirs, per-directory indexes, git with a daily sync — using OKF as the reference, not the product. Same desk as the opener: signal, data, answers — from an LLM wiki kept plain under OKF.
Because the contract is files on disk, a retrieval layer is additive and reversible. You can put one on top, and take it off, without rewriting the corpus. Next: Research wiki 3 — Search over the same files — when Open WebUI search helps on that read path, and when it doesn’t.
Pointers
- Prequel: Research wiki 1 — Agents as jobs
- Sequel: Research wiki 3 — Search over the same files
- OKF SPEC: Open Knowledge Format v0.1
- Why a format: Google Cloud — Introducing the Open Knowledge Format
- LLM-wiki pattern: Karpathy gist · Decoding AI
- Agent entrypoint pattern: LangChain OpenWiki