Skip to content

OKF Alignment Ideas

Jump to bottom
Chris Sweet edited this page Jun 25, 2026 · 5 revisions

type: analysis up: "SCHEMA_llm-wiki-memory-template" derived_from:

OKF Alignment Ideas

Working analysis of whether and how to align this template's wiki conventions with Google's Open Knowledge Format v0.1, filed 2026-06-25 after reading the actual spec (not just the blog post) and running an empirical link-rendering test against the live GitHub Wiki.

Question

Should the template adopt OKF v0.1 conventions, and if so, which of them, given that (1) GitHub Wiki imposes specific link-resolution behaviour that conflicts with OKF's recommended link form, and (2) the namespaced filenames (log_<repo>.md, index_<repo>.md, Home_<repo>.md) were introduced to let multiple wikis aggregate into a single Obsidian vault without collisions?

Context

OKF v0.1 specifies a deliberately minimal format: a directory of markdown files with YAML frontmatter, cross-linked by markdown links. One required frontmatter field (type); six optional reserved (title, description, resource, tags, timestamp). Reserved filenames index.md and log.md carry specific semantics (§6 and §7 of the spec). The recommended link form is absolute, with the .md suffix: [name](/path/file.md). Conformance is permissive: consumers MUST tolerate unknown types, unknown extra frontmatter keys, broken links, missing index files.

The template already implements the pattern OKF describes. The deltas live in three places: (1) reserved filenames (we namespace), (2) cross-reference syntax (we use bare slugs without .md), and (3) richer conventions OKF leaves to producers (typed edges, verification gate, multi-writer protocol, KG pipeline). See Lesson-Parallel-File-Drift for the framing-pattern context.

Empirical findings

A test page (OKF-Link-Test.md) and a non-namespaced log.md were pushed to the live wiki, rendered HTML scraped via curl, then removed (commits 7c79ef2 and 3b9b603). Results:

Link form authored Rendered href Click destination Verdict
[Display](Page-Name) (current convention) Page-Name (relative) /wiki/Page-Name rendered page ✓ works
[Display](Page-Name.md) (OKF style) Page-Name.md (relative) raw.githubusercontent.com/.../Page-Name.md raw markdown, no wiki chrome ✗ degrades
[Display](/Page-Name) (absolute, no .md) /Page-Name (absolute) github.com/Page-Name → 404 ✗ broken
[Display](/Page-Name.md) (OKF recommended) /Page-Name.md (absolute) github.com/Page-Name.md → 404 ✗ broken
[[Page-Name]] (Obsidian wikilink) class="internal present" href="/<owner>/<repo>/wiki/Page-Name" /wiki/Page-Name rendered page ✓ works, only form GitHub Wiki existence-checks

Reserved-filename test: log.md rendered correctly at /wiki/log. The namespacing was for Obsidian-vault aggregation, not a GitHub Wiki requirement.

Implication: OKF's recommended link form is not just stylistically different from ours, it is inherently incompatible with GitHub Wiki rendering. The .md suffix routes clicks to the raw-markdown CDN; the leading slash routes to github.com root rather than wiki root. There is no in-place edit to body links that satisfies both GitHub Wiki and OKF readers simultaneously.

Analysis

Three alignment vectors, each with its own option spectrum.

Vector 1: Frontmatter

Free wins. None of these conflict with GitHub Wiki, Obsidian, or our existing conventions.

Field OKF status Our status Recommendation
type required required ✓ already aligned
tags optional list optional list ✓ already aligned
description optional one-line summary implicit (opening sentence) Add as optional explicit field; redundant with opening line but cheap
resource optional URI for the underlying asset absent Add as optional; useful for source-summary pages anyway
title optional, defaults to filename implicit (H1) Skip; redundant with H1
timestamp optional ISO 8601 implicit (git history) Skip; git is more honest than a hand-maintained field
okf_version: "0.1" declared in root index.md frontmatter absent Add to index_<repo>.md (or index.md if we drop namespacing); signals OKF-style intent to any tool

Vector 2: Reserved filenames

Currently log_<repo>.md, index_<repo>.md, Home_<repo>.md. The reason: aggregating N derived wikis into one Obsidian vault flattens namespaces, so log.md from two repos would collide.

Three options:

  • A. Keep namespacing. No change. Cost: a strict OKF consumer reading our bundle does not recognise our log/index files as logs/indexes; they appear as ordinary concept files. We are non-conformant at the §3.1 reserved-filename layer.
  • B. Drop namespacing, fix the Obsidian aggregation by switching from "flat vault" to "subdirectory-per-wiki vault". Each wiki clones into vault/<repo>/; same-named files coexist because Obsidian disambiguates by path. Obsidian's [[Page-Name]] already resolves across subdirectories (path-disambiguated when ambiguous). Adopts OKF reserved filenames cleanly. Cost: small operational change in how the user maintains their vault; existing vault layout needs a one-time migration.
  • C. Dual write. Keep namespaced files as canonical, add log.md and index.md as auto-generated copies via a hook or build script. Cost: classic Lesson-Parallel-File-Drift footgun, exactly the failure mode the lesson warns against.

Recommendation: B, conditional on the user confirming the Obsidian-vault migration is acceptable. C is the worst of the three despite looking like a compromise.

Vector 3: Cross-link syntax

GitHub Wiki and OKF disagree at the syntax layer. The empirical results above make the conflict concrete.

Three options:

  • A. Keep [Display](Page-Name) (current). GitHub Wiki renders correctly. OKF readers see broken links (no .md suffix, no absolute path). Bundles do not round-trip cleanly.
  • B. Switch to [[Page-Name]] everywhere. Empirically the only form GitHub Wiki existence-checks (renders with class="internal present"). Also Obsidian-native (the whole vault model is built on [[wikilinks]]). Not OKF-conformant (OKF specifies markdown-link syntax). Cost: bulk migration of body links across ~30 pages.
  • C. Keep current source convention; add an OKF export step. A scripts/export-okf.sh walks the wiki and emits an OKF-conformant bundle (transforming [Display](Page-Name) to [Display](/Page-Name.md) and emitting log.md/index.md if vector 2 sticks with A). Cost: maintain a transform; one more parallel surface; another candidate footgun.

Recommendation: B is the best fit for what we already do (GitHub Wiki + Obsidian as the dual rendering targets) and gets us 80% of OKF compatibility almost for free, since [[Page-Name]] is one of the two link forms OKF examples show informally even though the spec recommends [name](/path/file.md). If hard OKF conformance for external exchange becomes a real requirement later, layer C on top.

Vector 4: Import direction (adopt.sh + OKF bundles)

Added 2026-06-25 after Priscila flagged that her in-progress scripts/adopt.sh (design at Adopt-Existing-Repo-Design) will support adopting OKF memory bundles as the initial wiki content of a repo that takes on the pattern. The first three vectors are about compatibility (us as a producer that other tools read) and export. This vector is the opposite: an external OKF bundle authored elsewhere becomes the seed of our wiki on adoption day.

Why this changes the weight on earlier vectors:

  • Vector 2 (reserved filenames) becomes load-bearing rather than cosmetic. An OKF bundle arrives with index.md and log.md at canonical paths. If we keep namespacing, every adoption pays a translation cost (rename, rewrite cross-links, update concept IDs); if we have already moved to OKF reserved filenames, the bundle slots in unchanged.
  • Vector 3 (cross-link syntax) loses its remaining alternative. OKF bundles bring [name](/path/file.md) body links, which we empirically proved are broken in GitHub Wiki rendering. The only viable normalisation target is [[Page-Name]], since the bare-slug [Display](Page-Name) form would still require a translation pass and wouldn't survive Obsidian-vault aggregation as cleanly. Adopting [[wikilinks]] as the canonical body-link form makes the import a single mechanical rewrite ([name](/path/file.md) → [[path/file]] or [[file]] once path-disambiguation rules are settled).
  • Vector 1 (frontmatter superset) earns its keep. Imported OKF concepts arrive with type, title, description, resource, tags, timestamp and nothing else. If our SCHEMA recognises those fields as first-class (rather than treating them as foreign), the import is identity on the frontmatter layer and only the body and cross-links need transformation. The OKF reserved fields become our reserved fields.

What adopt.sh --seed-from-okf=<bundle-path> (or whatever interface Priscila lands on) plausibly does:

  1. Validate the bundle is OKF-conformant per §9 (every non-reserved .md has parseable frontmatter and non-empty type).
  2. Copy the bundle tree into wiki/<repo>.wiki/ after init-wiki.sh has created the sub-repo.
  3. Rewrite body cross-links from [name](/path/file.md) to [[path/file]] (or whichever target form vector 3 lands on). Translation is mechanical and reversible because OKF link syntax is unambiguous.
  4. Optionally augment each concept's frontmatter with our richer edges (up:, extends:, supports: etc.) by inference from cross-links plus a type: untyped fallback for concepts whose OKF type value does not map to our vocabulary. Inference is opt-in because it is lossy and risks asserting relationships the bundle author did not intend.
  5. Emit a one-time wiki-corrections-log entry naming what was rewritten on import, so the provenance of the divergence from the original OKF bundle is auditable.

What this vector does not justify:

  • Coupling our wiki's source-of-truth representation to the OKF wire format. Import is a one-time event; the wiki then evolves under our richer conventions. We are not promising round-trip identity (round-trip would re-trigger the lossy edge-inference step on every cycle).
  • A standing reverse channel (wiki → OKF as continuous export). That's still vector 3 option C, still deferred unless external exchange becomes a real ask.
  • Bypassing the adoption manifest. The adopt design's .llm-wiki-adopt-log.md should record the seed bundle's source, version, and the rewrite policy applied at import. Otherwise a later contributor cannot tell why some pages have richer frontmatter than others.

Other deltas worth naming but not necessarily aligning

  • Log direction. OKF §7 says newest-first; ours is append-only oldest-last with ## [date] verb | subject headings and required by: attribution. Our convention is load-bearing: one-commit-per-entry maps cleanly to git log, and append-only gives git blame a faithful per-entry record. Don't flip; document the divergence.
  • Citation convention. OKF §8 specifies a numbered # Citations body section. We use the source: frontmatter edge. Both can coexist on the same page (the frontmatter edge stays the machine-readable form, the body section becomes the human-facing one). Cheap add for source-summary pages without losing what we have.
  • Typed edges. OKF §5.3 explicitly chooses untyped edges (link semantics carried by surrounding prose). Our extends:, supports:, criticizes:, related:, source: are an extension. Two responses, both optional: (a) document as a clearly-named local extension that any plain-OKF consumer can ignore safely, (b) propose upstream as an OKF minor-version backward-compatible add. Posture (a) costs nothing; posture (b) is worth attempting only if OKF gets material adoption traction.
  • Concept ID. OKF §2 defines concept ID as the file path minus .md. Our slug convention (Page-Name) already matches when files are at bundle root. The reserved-filename decision (vector 2) determines whether log_<repo> or log is the canonical concept ID.

Conclusion

Three changes I'd commit to if the user confirms the Obsidian-vault subdirectory migration is OK:

  1. Frontmatter superset. Add optional description:, resource:, and okf_version: "0.1" (the last only in index_<repo>.md or index.md). Update SCHEMA's Frontmatter section to name them as OKF v0.1 alignment fields.
  2. Reserved filenames. Drop the _<repo> namespacing for log.md, index.md, Home.md. Migrate the Obsidian aggregation pattern from "flat vault" to "subdirectory per wiki" in any doc that names it (likely a Cursor/Obsidian setup README and Adopt-Existing-Repo-Design).
  3. Cross-link syntax. Migrate body links from [Display](Page-Name) to [[Page-Name]]. Picks up GitHub Wiki existence-checking (currently absent), gets Obsidian-native rendering, gets partial OKF compatibility (Obsidian-style wikilinks are widely understood even outside the strict OKF spec).

Vector 4 strengthens this set: adopt.sh's OKF-bundle path is the strongest single argument for vectors 2 and 3. Without OKF-canonical reserved filenames and [[wikilink]] body links, every adoption pays a translation cost that compounds across imports and forecloses round-trip honesty about what was rewritten. With them, adopt-from-OKF is one cp -R plus one mechanical link-syntax pass.

Two changes I'd defer:

  1. OKF export script. Only if external bundle exchange becomes a real ask. Otherwise it is another parallel-file surface.
  2. Upstream typed-edge proposal. Only if OKF traction warrants. Posture (a) above (documented local extension) is free.

Three changes I'd not make:

  1. Flip log direction. Our one-commit-per-entry + by: attribution discipline is load-bearing and stronger than OKF's prose convention.
  2. Drop the verification gate, multi-writer protocol, or KG pipeline to fit OKF's deliberate minimalism. These are the discipline layer; OKF is the wire format. Conflating them collapses two distinct layers.
  3. Switch primary representation off GitHub Wiki. The empirical test confirms GitHub Wiki tolerates the moves above; no need to abandon it.

Open follow-ups

  • Confirm with the user whether the Obsidian-vault layout migration (flat → subdirectory-per-wiki) is acceptable. This decision gates vectors 2 and 3.
  • Test whether GitHub Wiki's [[wikilink]] form respects case-insensitive matching the way Obsidian does. The empirical test only checked the exact-match case.
  • Test whether GitHub Wiki tolerates [[Page-Name|Display Text]] (the piped Obsidian form). If yes, body links keep human-readable display text without falling back to markdown-link syntax.
  • Inventory cross-links across all pages so the syntax migration (option B in vector 3) is one mechanical pass instead of a drip of edits.
  • Decide where the OKF compatibility statement lives. Candidates: SCHEMA's "Relationship to other formats" subsection (new), llm-wiki.md, or a dedicated OKF-Compatibility.md.
  • Link-syntax translation policy on OKF import. When adopt.sh --seed-from-okf rewrites [name](/path/file.md) to [[…]], what is the wikilink target: full path ([[path/file]]) or basename only ([[file]])? Full path is safer against name collisions across subdirectories; basename matches Obsidian's default flat-namespace assumption and is what most wiki pages already use. Likely answer: basename when unambiguous, full path on collision. Worth confirming against a real OKF bundle before encoding.
  • Frontmatter back-fill defaults on OKF import. OKF concepts arrive with type, title, description, resource, tags, timestamp and no typed edges. Should adopt.sh infer up: from directory structure (parent dir's index.md becomes the parent)? Auto-derive extends: from cross-link patterns? Or refuse to infer and stamp type: untyped for any OKF type value not in our vocabulary? Inference is lossy and risks asserting relationships the bundle author did not intend. Conservative default: no inference, just copy through, let the verification gate flag type: untyped pages for hand-typing later.
  • Citation reconciliation on OKF import. OKF §8 specifies numbered # Citations body sections; we use the source: frontmatter edge. Options: (a) leave OKF's body section in place and add nothing to frontmatter (lossy in the KG direction), (b) parse the body section and populate source: automatically (lossy in the prose direction), (c) preserve both, body section as authored, frontmatter populated. Option (c) is the only one that loses nothing but doubles the surface area of citations.

See also

Clone this wiki locally