Skip to content

Knowledge Bundles Framing

Jump to bottom
Chris Sweet edited this page Jun 26, 2026 · 1 revision

type: synthesis up: "Home_llm-wiki-memory-template" derived_from:

Knowledge Bundles: Framing the LLM-Wiki Template

Brief for the paper agent. Reframes the llm-wiki-memory-template as an agentic knowledge-bundle system, using OKF v0.1 terminology as the formalisation anchor and naming the layers we add on top. Written 2026-06-26 against the assumption that the OKF-Alignment-Ideas recommendations are resolved (frontmatter superset adopted, reserved filenames OKF-canonical, body links migrated to [[wikilinks]], typed-edge ontology positioned as a companion spec via posture (c)). The "current implementation status" note at the bottom names what is shipped vs forward in the actual codebase as of today.

TL;DR

A knowledge bundle is a portable, git-distributable, agent-readable, human-readable directory of markdown files with structured frontmatter, conformant with OKF v0.1. The llm-wiki-memory-template is a system for creating, adopting, maintaining, federating, and querying knowledge bundles as agent durable memory. The contribution is not the bundle format (OKF supplies that) but the discipline layer: a verification gate, a multi-writer write protocol, a typed-edge ontology with materialised inverses, a KG query substrate, and a federation primitive (ask.sh) that lets agents query each other's bundles by clone-and-invoke. Two-line summary: bundles are the wire format, the discipline is the contribution, and the agent (not the human) is the primary maintainer.

Terminology (OKF-anchored)

Term OKF §reference Meaning in this system
Knowledge bundle §2 ("Knowledge Bundle") A directory of markdown files distributed as a git repo, tarball, or subdirectory. Our bundles live in wiki/<repo>.wiki/ as a separate git sub-repo.
Concept §2 One markdown file in the bundle. Identified by its path-minus-.md (the "concept ID").
Frontmatter §4.1 YAML metadata block. We use OKF's six reserved fields (type, title, description, resource, tags, timestamp) plus our typed-edge extension (up, extends, supports, criticizes, source, related, derived_from, decided_at).
Cross-link §5 Markdown link from one concept to another. We use [[Page-Name]] wikilink form (empirically the only form GitHub Wiki existence-checks and which works in Obsidian unchanged).
Index file §6 index.md enumerating a directory's concepts for progressive disclosure.
Log file §7 log.md recording history. We extend OKF's convention with append-only ordering, `## [YYYY-MM-DD] verb
Citation §8 External-source reference. We layer this onto a source: frontmatter edge for KG queryability while keeping OKF's body-section convention for prose readers.
Conformance §9 Permissive: tolerate unknown types, unknown frontmatter keys, broken links. Our extensions all sit inside this permissive envelope.

The shape OKF deliberately does not specify is the shape we contribute:

  • The agentic role in maintaining the bundle (who writes, who reads, who enforces discipline).
  • The operations (Query / Ingest / Lint) that turn a bundle from "a folder of markdown" into "an evolving artifact."
  • The edge semantics that turn the cross-link graph from a navigation aid into a reasoning substrate.
  • The multi-writer coordination that lets multiple agents safely edit one bundle concurrently.

The agentic stance

The bundle is agent durable memory. The agent (typically an LLM, e.g. Claude Code) is the primary maintainer. The human curates direction. Concretely:

Role Activity Cadence
Agent Read bundle to recall context. Write to bundle when work produces findings, decisions, or syntheses. Lint periodically. Run the verification gate before every write. Continuous within a session; every session for read; on milestones for write.
Human Provide raw sources, ask analytical questions, approve writes, set strategic direction. Steady; review-cadence.
Discipline layer (verification gate + write protocol + KG SHACL shapes) Enforce the conventions the agent self-applies. Catch projection-as-fact, missing back-references, missing log entries, edge violations. At each write.

The split rests on three observations Karpathy's llm-wiki gist made explicit and we operationalised:

  1. LLMs don't forget to cross-reference. A page added on Tuesday gets its back-references updated on Wednesday's adjacent edit, every time, mechanically.
  2. Markdown + frontmatter is a stable substrate for LLM reads and writes. No retrieval framework, no embedding index drift, no out-of-band metadata.
  3. The bundle compounds. A useful page added once is useful in every future session, where a RAG retrieval re-derives the same insight every time.

OKF v0.1 ratifies (2). The llm-wiki template adds the discipline that makes (1) and (3) load-bearing.

Bundle lifecycle

Five operations, each grounded in a script or skill that ships with the template.

1. Create — scripts/instantiate.sh

Scaffold a new bundle in a fresh repo. Generates a CLAUDE.md (or AGENTS.md), initialises wiki/<repo>.wiki/ as a sibling sub-repo via wiki/init-wiki.sh, installs the agent overlay (Claude Code, Cursor, or none), seeds the bundle with namespaced index.md, log.md, Home.md, a SCHEMA reference page, and the typed-edge vocabulary at Edge-Types.md.

2. Adopt — scripts/adopt.sh

Take on the pattern non-destructively in a repo that already exists. Uses an inverted authority model: a template-owned ADD allowlist for files adopt creates, a host-owned TOUCH grants file (.llm-wiki-adopt-grants.yml) the host author writes by hand to explicitly authorise managed-block, append-only, or merge touches to specific pre-existing files, and a runtime-computed NEVER-TOUCH set covering everything else. The --seed-from-okf=<bundle> mode (Vector 4 of OKF-Alignment-Ideas) accepts an existing OKF bundle as the starter wiki content, applying mechanical link-syntax rewrites and emitting a corrections-log entry recording the import policy. Detail: Adopt-Existing-Repo-Design.

3. Maintain — Query, Ingest, Lint (the Three-Operations)

  • Query: read index.md, drill into relevant concepts, synthesise an answer. Optional: KG query over the typed-edge graph (scripts/kg/build-graph.sh → SPARQL via rdflib + pyshacl).
  • Ingest: after significant work, create or update concepts; fix cross-references on every affected page in both directions; update index.md; append an entry to log.md; run the Verification-Gate; commit.
  • Lint: orphans, dead links, stale claims, missing frontmatter, edge-vocabulary violations, redundant or untyped pages.

The agent runs these operations proactively (default), or the human invokes them via slash commands (/wiki-source, /wiki-experiment, /wiki-lint) when explicit framing is wanted.

4. Federate — scripts/agent-comms/ask.sh

Discover and query a peer agent's bundle without absorbing its content. Federation index at la3d-llm-agents.github.io projects synthetic Cards from each member's Card_<repo>.md (or, per Vector 5 of OKF-Alignment-Ideas, from any OKF bundle's root index.md when it declares okf_version). ask.sh clones the peer's bundle into ~/.llm-agents/wikis-cache/, cd's in, runs claude -p "<question>", prints the answer. The peer never knows it was asked. The pattern is direction-agnostic: query targets can be template-derived wikis, pure OKF bundles, or anything cloneable with frontmatter and markdown. Detail: Comms-Feature-Design (agent-comms wiki).

5. Compose — Obsidian-vault aggregation

Each bundle clones into its own subdirectory of a single Obsidian vault (vault/<repo>/). Obsidian's path-disambiguated [[wikilinks]] resolve across subdirectories, so same-named files (index.md, log.md, Home.md) coexist cleanly. The human reads multiple agents' bundles as one navigable graph; the per-bundle git history stays intact.

Where we extend OKF

Five layers, each named with the substrate page that documents it. None require OKF v0.1 spec changes; all sit inside OKF §4.1's preserve-unknowns envelope.

Layer What it adds Substrate
Typed-edge ontology Forward predicates (extends, supports, criticizes, source, up, related, derived_from) and pipeline-materialised inverses (extendedBy, supportedBy, criticizedBy, ...). Each edge carries an interface contract: traversal licenses a specific agent operation (inherit context, aggregate evidence, detect contradiction, ground claim, navigate hierarchy). Typed-Edges-and-Frontmatter, Edge-Types (rendered into each bundle), positioned as a separable "OKF Typed Edges Extension" companion spec per posture (c) of OKF-Alignment-Ideas.
Verification gate Procedural pre-commit check the agent runs over every draft: numerical claims tagged with corpus, every typed-edge reference has a body-level back-reference, frontmatter valid, index updated, log entry appended, honest reporting (no projection-as-fact). Verification-Gate.
Multi-agent write protocol Collision-free wiki sub-repo writes via Optimistic Concurrency Control with semantic retry. Union-merge for log and index files (mechanical); semantic resolution only when same lines of same section conflict. Bayou-lineage prior art with the LLM as the retry's semantic resolver. Multi-Agent-Write-Protocol, Analysis-of-Wiki-Push-Race-Pattern.
Knowledge-graph pipeline rdflib + pyshacl + SHACL shapes over the typed-edge frontmatter. Topology queries ("which pages support this claim?", "what extends this concept?") via SPARQL; content queries fall back to file reads. Two retrieval shapes, one for "what connects to what," one for "what does this page say." Knowledge-Graph-Pipeline.
Sync flow + governance Template improvements propagate to derived bundles via update-from-template.sh and an ALWAYS_FILES contract. Three-tier governance (base / variant / derived project) frames where new features land. Sync-Flow, Governance.

Cross-cutting properties

Each of these is what makes the system useful as agent memory; none come for free from OKF alone.

  • Compounding. A useful page added once is useful in every future session. Compare to RAG over a static corpus: every retrieval re-derives the same insight, the artifact does not improve.
  • Portable. Just files in git. No runtime, no daemon, no central authority, no embedding index to keep in sync. A bundle ships as .tar.gz or git clone and runs anywhere the agent runs.
  • Auditable. Git history + the by: attribution + verification-gate receipts + the corrections-log produce a faithful per-page provenance. The wiki is a shared memory across agents and humans; provenance is answerable on the page, not only through git blame.
  • Multi-agent safe. The write protocol handles concurrent writers without requiring a coordinator. The 2026-06-12 web_forager production collision (3-4 human+agent teams; 20 commits of drift; log-file conflict) is exactly the failure the protocol prevents by construction.
  • Federable. Bundles are queryable as peers via ask.sh. Federation discovery is GitHub-native (org membership + topic + trusted-owner allowlist); no separate API. Cross-bundle composition is filesystem-native (Obsidian vault aggregation).
  • Interoperable. OKF v0.1 conformant. Any OKF-aware tool can read our bundles. Plain markdown for humans without tooling. The typed-edge extension is opt-in for OKF consumers and machine-checkable via SHACL.

Honest limits

These are not claims of the system. The paper agent should not paper over them.

  • Not a query engine. The KG pipeline answers topology questions (multi-hop, hub detection, edge-typed traversal). Content questions (definitions, prose claims, specific numbers) are answered by reading the relevant file. We use the KG to discover where to look, then file tools to read what the chosen pages say.
  • Not a runtime. No daemon, no scheduler, no coordinator. Agents pull, edit, commit, push. The multi-agent protocol is a discipline + a small bash library, not a service.
  • Not multi-machine real-time. The agent-comms mailbox substrate is local-filesystem-only. Cross-machine federation rides on git clone over GitHub; latency is whatever git is.
  • Not all aspirational pieces have shipped. The multi-agent write protocol prototype is implemented but not yet wired into the agent overlay's default write path (only the 9 CI scenarios call it directly today). The OKF alignment proposed in OKF-Alignment-Ideas is at the analysis stage; the migration to reserved-filename canonical names and [[wikilinks]] is pending a user decision on the Obsidian-vault layout. The companion typed-edge spec (posture (c)) is named as the target but not yet packaged as a separable artifact.
  • Discipline is enforced procedurally, not mechanically. The verification gate is a checklist the agent self-applies; the PostToolUse hook is advisory; the gate fails only if the agent reads itself honestly. Lesson-Hook-Type-Matters names this: prompt-type hooks cannot be advisory the way the model can ignore them, and we have explicitly accepted that trade in exchange for keeping the gate criteria editable in markdown rather than baked into code.
  • Single-writer remains the dogfood default; multi-writer is the empirical reality. Lesson-Template-Contribution-Discipline and Analysis-of-Wiki-Push-Race-Pattern name this honestly: the team-of-one assumption survived too long in our own framing; production wikis routinely have 3-4 writers.

Naming and positioning for the paper

Suggested vocabulary the paper agent can use without coining new terms:

  • "Agentic knowledge bundles" — the system class (knowledge bundles where the agent is the primary maintainer, not the human).
  • "OKF + discipline" — what the template adds on top of the bundle format.
  • "Compounding agent memory" — the property that distinguishes this from RAG.
  • "The discipline layer" — verification gate + write protocol + KG + SHACL shapes, collectively.
  • "Bundle federation" — the ask.sh clone-and-invoke pattern; the federation index is the discovery layer.

Suggested framing the paper agent should avoid:

  • Calling this a "knowledge graph" without qualification. The KG is one substrate among several; the bundle is the primary artifact and most reads are over files, not the KG.
  • Calling this "a wiki" as if the wiki is the contribution. The wiki is the substrate format. OKF supplies the format; the contribution is the discipline that makes the format usable as agent durable memory under multi-writer pressure.
  • Overclaiming "AI-native" or "agent-first" without naming what the agent actually does differently from how a human would maintain a wiki. The concrete difference is mechanical cross-reference maintenance, scheduled lint, proactive ingest on every significant work product, and the verification-gate self-discipline that catches projection-as-fact at write time.
  • Treating OKF as a competitor. It is the format we conform to. Position the work as "OKF + the discipline layer."

Current implementation status (2026-06-26)

What is in main of crcresearch/llm-wiki-memory-template today versus what this brief assumes as resolved.

Layer Shipped Forward
OKF v0.1 conformance type: required, tags: optional, frontmatter-permissive description, resource, okf_version, [[wikilinks]], OKF-canonical reserved filenames pending user sign-off on Obsidian-vault subdirectory aggregation
Typed-edge ontology Edge-Types.md.template rendered into each bundle; inverses materialised by KG build (PR #29) Repackaging as separable "OKF Typed Edges Extension v0.1" companion spec (posture (c))
Verification gate wiki/agents/verification-gate.md agent-agnostic procedure; criteria editable No mechanical enforcement; advisory only
Multi-agent write protocol Prototype at scripts/wiki-write-protocol/ with 9 CI scenarios green Default-path wiring (wiki_push) pending PR7 of the write-protocol cluster
KG pipeline scripts/kg/build-graph.sh shipped PR #14; rdflib + pyshacl + optional Fuseki Inverse-edge SHACL spec; PostToolUse write-time check
Federation primitive (ask.sh) Shipped via PR #44; discovery + clone-and-invoke working against live federation; 264 assertions green OKF-bundle synthetic Cards in the federation index; OKF-aware preamble in ask.sh
Adopt path (adopt.sh) In progress on feature/adopt-sh; advisory-abort detector + Tier-1 fixtures green on macOS bash 3.2 and Linux --seed-from-okf mode (Vector 4) pending

Reading order for someone coming to this fresh: Wiki-LLM-Pattern → Three-Operations → OKF-Alignment-Ideas → Typed-Edges-and-Frontmatter → Verification-Gate → Multi-Agent-Write-Protocol → Adopt-Existing-Repo-Design. This brief is the synthesis; those are the load-bearing detail pages.

See also

Clone this wiki locally