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.

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).

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.

See also

Clone this wiki locally