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.

Vector 5: Query direction (ask.sh + OKF bundles)

Added 2026-06-25 after the user pointed at the agent-comms feature (Comms-Feature-Design, shipping in PR #44) and its scripts/agent-comms/ask.sh primitive. The pattern is: discover a peer via the federation index, clone (or fast-forward pull) its wiki sub-repo into ~/.llm-agents/wikis-cache/<owner>/<repo>/, cd in, and run claude -p "<question>" against the cloned bundle. The peer never knows it was asked; the response is the LLM's reading of the bundle.

The pattern does not require the target to be a template-derived wiki. claude -p is invoked against a directory of markdown plus frontmatter. An OKF bundle, by construction, is a directory of markdown plus frontmatter. Any OKF bundle reachable as a git clone is queryable by ask.sh today, given two small affordances:

  1. A federation index entry. Today the federation index at la3d-llm-agents.github.io is populated from Card_<repo>.md files in template-derived wikis. For an OKF bundle to be discoverable, either: (a) the bundle author publishes a Card alongside the bundle (a small overlay), or (b) the rebuild Action projects a synthetic Card from the bundle's root index.md frontmatter (okf_version: "0.1" plus description: plus the bundle's git URL). (b) is the more honest move because it doesn't require OKF bundle authors to adopt our convention; (a) wins when the bundle author wants control over the projection.
  2. A target the LLM can interpret without our context. ask.sh cd's into the cloned wiki and invokes claude -p. The LLM session has no CLAUDE.md, no SCHEMA, no slash commands; it sees only the bundle's own files. For a template-derived wiki this works because we also clone the surrounding project's CLAUDE.md and SCHEMA_<repo>.md (those live in the wiki sub-repo, not the parent project). For a pure OKF bundle, the LLM is interpreting raw OKF v0.1 + markdown body. Modern models handle that capably from frontmatter alone, but answer quality varies with how self-describing the bundle is. Pain trigger: ship a tiny inject step in ask.sh that prepends the OKF spec (or a one-line "you are reading an OKF v0.1 bundle" preamble) to the prompt when the target's root index.md declares okf_version.

Why this is a separate vector from import (vector 4):

Direction Operation When you'd use it
Vector 4: import clone + rewrite + absorb into your wiki, one-shot, persistent The bundle's knowledge is foundational and you want it as your starting wiki content. Adopt-and-evolve.
Vector 5: query clone + claude -p, recurring, ephemeral You want answers without taking ownership of the knowledge. Read but don't absorb. Cache the clone, not the answers.

The two are complementary. A repo that has adopted the template (via adopt.sh) AND federates via agent-comms can both seed itself from an OKF bundle once (vector 4) AND continue to query other OKF bundles forever (vector 5). The vectors share infrastructure (git clone, conformant frontmatter, [[wikilink]] or no-link bodies that an LLM can navigate) but answer different questions.

What this means for the earlier recommendations:

  • Vector 1 (frontmatter superset) compounds. Same fields used for OKF compatibility are used for federation projection. okf_version: "0.1" in the bundle's root index.md is the signal both directions need: vector 4 uses it to validate the import target, vector 5 uses it to project a synthetic federation Card.
  • Vectors 2 and 3 stay justified for vector 4 reasons (import friction). Vector 5 is more permissive: query doesn't care whether the target uses [[wikilink]] or [name](/path.md), since the LLM reads both. Query only needs the bundle to be self-describing enough for the LLM to traverse it.
  • No reverse coupling. Just as vector 4 doesn't promise round-trip identity, vector 5 doesn't promise stable answers. Two ask.sh invocations against the same bundle at the same SHA can produce different prose answers; that's a feature of the query path, not a bug to fix.

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: (plus their pipeline-materialised inverses extendedBy, supportedBy, criticizedBy, ... per PR #29, plus the page-type vocabulary concept, synthesis, analysis, decision, source-summary, comparison, index, entity) form a real ontology on top of OKF's minimal frontmatter. The whole vocabulary is already spelled out in wiki/Edge-Types.md.template (rendered into each derived wiki's Edge-Types.md); that file is effectively our companion ontology spec, just not labeled as such. Three postures, smallest to biggest:
    • (a) Documented local extension. Edge-Types.md stays as-is; plain-OKF consumers ignore the edges safely per §4.1's preserve-unknowns rule. Zero cost. Limit: nobody else can interpret our edges without reading our docs.
    • (b) Upstream proposal. Pitch the typed-edge vocabulary as an OKF minor-version backward-compatible addition. Costs are real (write the proposal, engage with Google's spec process, accept that the design will be re-negotiated). Worth attempting only if OKF gets material adoption traction we don't yet have evidence for.
    • (c) Separate companion spec. Repackage Edge-Types.md as a self-contained "OKF Typed Edges Extension v0.1" that any OKF tool can opt into without OKF v0.1 changes. Mirrors how RDFa, microdata, and Schema.org evolved as layered extensions on top of HTML rather than as HTML spec changes. Concrete artifacts: a spec document (Edge-Types content + a conformance section), the SHACL shapes file we already have for the KG pipeline as the machine-checkable form, and a tiny "consumers SHOULD" clause covering inverse-edge materialisation. Pays off if our edges have value to anyone else doing OKF-style work, even before OKF adopts them; (b) is then a downstream move once the companion spec has receipts.
  • 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.

Vector 5 widens the surface in a different direction: ask.sh's clone-and-invoke pattern generalises the federation from "template-derived peers only" to "any cloneable OKF bundle that declares itself." The federation index already projects from frontmatter; extending it to project a synthetic Card from an OKF bundle's root index.md (when okf_version: "0.1" is declared) costs the rebuild Action a few lines and unlocks query against the entire OKF ecosystem.

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.
  • Federation index projection for pure OKF bundles. Extend the la3d-llm-agents.github.io rebuild Action to recognise an OKF bundle's root index.md (signalled by okf_version: "0.1" in frontmatter) and project a synthetic federation Card from it (description: plus the bundle's git URL, plus provenance: "okf" so downstream tools can tell it apart from Card_<repo>.md-authored entries). Open: does projection require the bundle author's opt-in (a topic, an org membership, an allowlist entry) or does any reachable bundle qualify? Likely answer: same nd-llm-wiki topic + trusted-owner allowlist already used for cross-org agent discovery; bundles outside that scope stay invisible.
  • OKF-aware ask.sh preamble. When the target of ask.sh declares okf_version: "0.1" in its root index.md, prepend a short "you are reading an OKF v0.1 bundle, conventions are X/Y/Z" preamble to the claude -p prompt. Without this, the LLM has to infer the bundle's structure from its frontmatter on every invocation. Cheap; trigger is observed quality variance on pure-OKF query targets.

See also

Clone this wiki locally