ADR · Proposed (2026-05-27 grilling session)

LLM Wiki pattern for the Knowledge Base (per-teacher repo)

Date

2026-05-27

Deciders

pdg (HITL during the 2026-05-27 grilling)

Companion design

docs/superpowers/specs/2026-05-27-v2-claude-code-style-redesign.md § 3.9

External reference

Karpathy's LLM Wiki gist (2026-04-04)

Context

Collapsed's KB layer has three components: KB Librarian (files candidate sources with S/A/B tier gate), KB Context Researcher (T0 cosine search + rerank), KB Field Researcher (autonomous deep-research). All stored in Supabase tables.

The V2-P1 spec deferred KB ('no KB / RAG, references stand-in'). With the substrate change to git-as-truth (ADR 0004), the KB needs a new home that doesn't reintroduce JSONB.

Karpathy published the 'LLM Wiki' gist on 2026-04-04 — a pattern for persistent, compounding LLM-maintained knowledge bases as an alternative to RAG. Within two weeks: 5,000+ stars. The fit with V2's design is exact.

Decision

The V2 KB implements Karpathy's LLM Wiki pattern as a per-teacher git repo, with the Task primitive + prompts handling all four verbs.

D36 — Substrate (B): per-teacher KB repo. Cross-course accumulation within a teacher. Cross-teacher sharing is future (institutional shared-mount).
D37 — Integration pattern (ii): Task-based query. Course sub-agents invoke Task with kb/context-researcher.md. Returns curated pages, not raw KB.
D38 — Page schema + KB repo structure follows Karpathy's three-layer model exactly.
D39 — KB linter (kb/linter.md) runs periodically. Audits for contradictions, stale claims, orphan pages, missing concepts.
D40 — File-back affordance in chat dock footer: 'File as KB page' converts resolved chat segment into kb/pages/<slug>.md.
D41 — Left sidebar 'Knowledge Base' section: tiered (S/A/B) link tree into the teacher's KB repo.

KB repo structure (follows Karpathy)

Path	Layer	Purpose
kb/AGENTS.md	Schema	Defines page conventions, frontmatter, workflows
kb/index.md	Catalog	Link + 1-line summary per page
kb/pages/*.md	Wiki core	Mutable, LLM-authored knowledge pages
kb/sources/*.md	Raw sources	Immutable, markdown-converted
kb/media/	Assets	Extracted/harvested images, diagrams
git history	Log (replaces Karpathy's log.md)	Chronological feed via git log

Four verbs as prompts

Karpathy verb	V2 prompt	Trigger
Ingest	kb/librarian.md	Teacher uploads source; or Field Researcher writes new page
Query	kb/context-researcher.md + kb/relevance-judge.md	Course sub-agent Task-invokes; teacher search
Lint	kb/linter.md	Periodic cron + on-demand
File-back	kb/librarian.md (chat-segment input)	Per-chat-resolution affordance

Where V2 improves on Karpathy's base pattern

Git replaces log.md — free, signed, diffable chronology.
Vector search + rerank built in from day one — scales beyond Karpathy's ~100-source ceiling.
Bound tools per sub-agent — mechanical scope safety Karpathy doesn't have.
Per-teacher boundary aligns with the teacher dashboard structure.

Consequences

Positive

• Cross-course compounding — Course A's research populates KB; Course B benefits without re-research.
• Cheap audit — git log kb/pages/<page>.md shows full provenance.
• Iterable schema — updating kb/AGENTS.md propagates to subsequent ingest/query/lint.
• Karpathy's improvements come for free as the community pattern evolves.

Negative

• Migration cost from kb_pages table to filesystem (~1 week, not in V2-P1 critical path).
• KB lint scheduling needs a worker queue (deferred per ADR 0004 Q-OPEN-1).
• Embeddings re-compute path needed on page change.

Neutral

• 3 collapsed KB agents collapse to 5 prompts (adds Relevance Judge + Linter).
• Institutional KB is a future upgrade via shared-mount + RLS extension.

Migration / execution

1.Wave R5: per-teacher KB repo bootstrap, kb/AGENTS.md system default, 5 KB prompts, course sub-agent wiring, file-back UI affordance, left-sidebar tiered render.
2.Cutover (V2-P6): existing kb_pages rows → kb/pages/*.md, kb_sources → kb/sources/*.md, embeddings re-computed.

Open questions

Cross-teacher sharing (institutional KB) via shared-mount — designed as future, not V2-P1+.
Embeddings re-compute trigger — post-commit hook vs lazy-on-query.
Source upload format support — PDF, HTML, EPUB. Decided at R5.

← Previous

0005 · Prompts-as-agents: one Task primitive + N markdown prompts

0007 · Revert the V2 LLM-Evaluator deletion (commit 0e0703d)

ADR index

Context

The V2-P1 spec deferred KB ('no KB / RAG, references stand-in'). With the substrate change to git-as-truth (ADR 0004), the KB needs a new home that doesn't reintroduce JSONB.

Decision

The V2 KB implements Karpathy's LLM Wiki pattern as a per-teacher git repo, with the Task primitive + prompts handling all four verbs.

D36 — Substrate (B): per-teacher KB repo. Cross-course accumulation within a teacher. Cross-teacher sharing is future (institutional shared-mount).

D37 — Integration pattern (ii): Task-based query. Course sub-agents invoke Task with kb/context-researcher.md. Returns curated pages, not raw KB.

D38 — Page schema + KB repo structure follows Karpathy's three-layer model exactly.

D39 — KB linter (kb/linter.md) runs periodically. Audits for contradictions, stale claims, orphan pages, missing concepts.

D40 — File-back affordance in chat dock footer: 'File as KB page' converts resolved chat segment into kb/pages/<slug>.md.

D41 — Left sidebar 'Knowledge Base' section: tiered (S/A/B) link tree into the teacher's KB repo.