Adopt Open Knowledge Format (OKF) compatibility: migrate onboarding headers to YAML frontmatter

[Foxfire1st]

Summary

Adopt Open Knowledge Format (OKF) compatibility for our onboarding memory, starting with migrating onboarding metadata headers from Markdown | Field | Value | tables to YAML frontmatter.

OKF (v0.1, from GoogleCloudPlatform) is an open, minimal format for agent/human knowledge: a directory of markdown files with YAML frontmatter. Google independently landed on the same substrate Agents Remember already uses — markdown + frontmatter + git, explicitly rejecting proprietary schemas and vector-store lock-in. Aligning to it is low-cost interop and standards credibility, and it signals the repo is aware of and moving with the emerging standard.

Crucially, OKF is format-only: its spec explicitly defers governance ("No permissions layer specified") and orchestration ("data format only, not infrastructure"), and treats freshness as an optional self-reported timestamp. That is exactly the line below our moat — our git-verification, drift detection, governed worktree/closeout gates, and the code↔memory ledger all live above the format. So we can speak the standard without giving up a thing.

Where we stand against OKF v0.1 conformance

OKF has only three hard MUSTs. We satisfy #3 vacuously (we ship no files literally named index.md/log.md). We currently fail #1 ("every non-reserved .md file contains a parseable YAML frontmatter block") and #2 ("non-empty type field") — and both fail for the same single reason: our metadata is a Markdown table keyed doc_type, not a YAML --- block keyed type.

The entire conformance gap is one serialization decision. Everything OKF actually models, our onboarding already carries.

Field mapping

OKF field	Req?	Our field today	Action
type	required	doc_type (file-level-onboarding, repo-overview, repo-entity-catalog)	rename/alias to type (values already are concept types)
title	recommended	H1 # <path>	lift into frontmatter (or let consumers derive from filename)
description	recommended	first line of ## Purpose	optional: lift one sentence into frontmatter
resource	recommended	path	map path → resource (the asset the concept describes)
timestamp	recommended	lastUpdated	rename to timestamp (ISO 8601)
tags	recommended	—	optional
extension keys	MAY (preserved)	lastVerifiedCommitHash, lastVerifiedCommitDate, governingOverview, sourceRoute/sourceScope, git-blob-set-v1 fingerprints	keep as OKF extension keys — this is the verification moat

OKF states producers MAY add any keys and consumers SHOULD preserve unknown keys. So our verification fields stay, and we stay conformant. The upgrade in one line: OKF's timestamp says "when I last changed"; our lastVerifiedCommitHash says "the exact commit I was proven against" — git-verified, not just git-resident.

Before / after (one real sidecar)

Before (onboarding/.../memory_ledger.py.md):

# mcp/src/agents_remember/kernel/memory_ledger.py

| Field | Value |
| --- | --- |
| repository | agents-remember |
| path | `mcp/src/agents_remember/kernel/memory_ledger.py` |
| doc_type | `file-level-onboarding` |
| lastUpdated | 2026-05-31T12:30+02:00 |
| lastVerifiedCommitHash | `c20a3292...` |
| lastVerifiedCommitDate | 2026-05-31T14:17:11+02:00 |
| governingOverview | `../../../overview.md` |

After (OKF-conformant):

---
type: file-level-onboarding
title: mcp/src/agents_remember/kernel/memory_ledger.py
description: Parses, validates, and updates the external-memory memory.md ledger mapping code↔memory commits.
resource: mcp/src/agents_remember/kernel/memory_ledger.py
timestamp: 2026-05-31T12:30:00+02:00
# Agents Remember verification extensions (OKF extension keys; preserved by conformant consumers)
repository: agents-remember
lastVerifiedCommitHash: c20a3292e667d227a3be0c1fb276f8a701df814f
lastVerifiedCommitDate: 2026-05-31T14:17:11+02:00
governingOverview: ../../../overview.md
---

# mcp/src/agents_remember/kernel/memory_ledger.py
...

Proposed scope (phased, all tracked in this issue)

Phase 1 — YAML frontmatter migration (the core):

• Migrate onboarding metadata headers (file-level sidecars, route overview.md, entities.md) from Markdown tables to YAML frontmatter.
• doc_type → type; lastUpdated → timestamp; add resource (= source path) and title.
• Keep verification fields (lastVerifiedCommitHash, lastVerifiedCommitDate, governingOverview, sourceRoute/sourceScope, fingerprints) as OKF extension keys.
• Move the c-02-memory-quality-control drift parser and c-05-create-or-update-onboarding-files templates from table-parsing to YAML-frontmatter parsing; keep update-history style checks working.
• One-time converter run across all onboarding under the resolved onboarding root.

Phase 2 — OKF reserved files & citations:

• Generate OKF index.md from the data already in overview.index.json.
• Optionally project ## Update History → per-directory log.md (ISO date headings, newest-first).
• Normalize the References sections (Docs / Repo-Internal / Cross-Repo) toward an OKF # Citations block.

Phase 3 — Conformance check & public claim:

• Add an OKF-conformance check to memory_quality (assert every non-reserved .md has parseable frontmatter + non-empty type).
• Document the "OKF-compatible" claim in the README (concepts + verification extensions).

Impact / things to watch

• The onboarding header parser used by c-02-memory-quality-control drift checks and the c-05-create-or-update-onboarding-files templates must move from table-parsing to YAML-frontmatter parsing. This adds a YAML read dependency to the onboarding path.
• The update-history style checks (memory_quality/style/update_history/*) must keep working against the new header shape.
• The memory.md ledger is a separate artifact (its own JSON+table grammar, deliberately dependency-free) and is out of scope here — decide separately whether it ever moves.
• Migration should be mechanical and verifiable: a one-time converter plus a conformance check, run across all existing onboarding under the resolved onboarding root.

Why now

This is a direction signal as much as a feature: it states that Agents Remember tracks the emerging open knowledge standard and positions our onboarding as "OKF concepts + verification extensions" — we speak the standard, and we add the part (git-verified freshness, drift, governance) the standard deliberately leaves to the layer above it.

Note: detailed task shaping (build mode, worktree, plan) goes through the normal session lifecycle; this issue is the proposal + direction record, not a committed plan.