Kb

kb CLI and Knowledge Base Pattern

kb maintains an Obsidian markdown knowledge base in the Karpathy LLM Wiki pattern. kb ingests sources, and its decision model gates, classifies and links them. You, the agent, compile wiki articles from the sources, answer questions from the wiki and file the answers back, and run lint-and-heal passes.

• Topic. Each topic is a folder in the vault: at the root (go-best-practices/) or nested by [vault].topic_globs (harness/goclaw/). CLAUDE.md is the topic marker and schema document (scope, conventions, current articles, gaps; AGENTS.md may symlink to it). topic.yaml holds slug, title, domain, mode and the selection contract. kb renders the contract into CLAUDE.md under ## Selection contract; change it with kb topic contract, never in CLAUDE.md.
• Mode. mode: wiki (default; raw/, wiki/, outputs/, bases/, log.md, the ingest → compile → query → lint loop) or mode: okf (a flat, portable Open Knowledge Format bundle of typed concepts, filled by kb promote).
• Division of labour. The decision model only judges text (yes/no, choice, score) and a small generation model only writes short literals (summaries, criteria, aliases, drafts); code applies thresholds and writes files. You write and update article prose, decide what to ingest, draft or edit contracts, and give the human verdicts in kb review.

references/architecture.md has the rationale (compiler analogy, context window vs RAG, multi-topic vaults).

Prerequisites

• kb version works. qmd --version for kb index/kb search and optional vector candidates (npm install -g @tobilu/qmd).
• OPENROUTER_API_KEY for every command that ingests (except codebase), classifies, links, finds, drafts or accepts a contract, builds a vocabulary, accepts or rejects review items, or suggests an OKF type. Those commands refuse to start without it. lint, inspect, index, search, topic new|list|info, topic contract --import-claude, review list|import-links|import-labels|calibrate, find --facets, ingest codebase and migrate never call a model.
• FIRECRAWL_API_KEY for kb ingest url; yt-dlp (and an STT key for --transcribe auto|stt) for YouTube and Instagram.
• A repo-root vault has kb.toml at its root:

  [vault]
  root = "."
  topic_globs = ["*", "harness/*"]

Command map

Use path-relative topic ids for nested topics (--topic harness/goclaw). For parsing, use --format json where a command offers it and read stdout only; stderr carries diagnostics and run summaries (output-formats.md).

Working with the decision model

These rules apply to every decision-backed command; references/decision-workflow.md has flags, thresholds, queue actions, calibration and the .decisions/ files.

• Budget. --budget <usd> caps a run (default US$ 1). --budget 0 uses cached answers only. Past the budget, items are undecided:budget: re-run to continue from the cache in <topic>/.decisions/receipts.jsonl.
• Failures are never a "no". undecided:<reason> and not_checked:<reason> leave a document as it was, and an undecided ingest judgment writes triage: review with triage_reason: undecided. Report these statuses from the run summary; re-run instead of concluding anything from them.
• Shadow before apply. Relevance gates and body-link insertion run in shadow (recorded as review items, nothing moved) until the topic has an accepted contract and a current calibration or decisions.gates: apply / decisions.mode: apply. Quality gates and exact dedupe apply from the start. Never switch a topic to apply without the user.
• Nothing is deleted. Gated sources move to raw/_quarantine/ with a ledger of every index line and frontmatter entry removed, so kb review accept restores them byte for byte. Quarantine and restore only through kb review, never by moving files.
• Frontmatter ownership. kb writes its own keys (triage, genre, depth, relevance, concepts, summary, criterion, entities, questions, quality, relation lists, aliases, ...; frontmatter-schemas.md). A key you or the user edit becomes user-owned and kb stops writing it (lint: key-conflict); relation lists and aliases only get appended to. locked: true makes kb skip a file entirely. topic.yaml decisions.exclude globs keep files out of every model call.
• Human verdicts. Review items are yours or the user's to decide. Read items before bulk-accepting (--above, --topic-wide); several wrong remove items mean the contract is too narrow. Every verdict becomes a calibration label.

KB maintenance procedures

Procedure 1: Compile a wiki article

1. Read references/compilation-guide.md for length, style, wikilink density, sourcing and update rules.
2. Find candidate sources: kb find <topic> "<what the article must cover>" --explain, sources whose concepts: or affects: name the article, kb search "<phrase>" --topic <topic>, or <topic>/wiki/index/Source Index.md. For a stub (stage: stub), its criterion says what the article must cover.
3. Load the candidate sources fully, and <topic>/wiki/index/Concept Index.md for existing articles and wikilink targets.
4. Before drafting, present 3–5 key takeaways, the concepts the article introduces or updates, and any contradiction with existing articles; ask what to emphasize, unless the user asked for autonomous compilation.
5. Write <topic>/wiki/concepts/<Article Title>.md (Obsidian Flavored Markdown; frontmatter from frontmatter-schemas.md; 3000–4000 words; Sources section). Updates to an existing article use the Current / Proposed / Reason / Source diff format from compilation-guide.md.
6. Run kb classify <topic> --only-missing (criterion and aliases for the new article), then kb link <topic>, and work kb review <topic> --queue link. kb finds the mentions and writes the backlinks; you do not hand-audit them.
7. Update the topic indexes (Procedure 2) and the current-articles list in <topic>/CLAUDE.md; re-index with kb index --topic <topic> when the topic uses QMD.
8. Append ## [YYYY-MM-DD] compile | <Article Title> (<words> words, <N> sources) to <topic>/log.md.

Procedure 2: Maintain topic indexes

After adding, renaming or removing a wiki article, update <topic>/wiki/index/Dashboard.md (counts, featured sections, Base embeds), Concept Index.md (alphabetical row with a one-line summary) and Source Index.md (every cited source with a wikilink back to the article).

Procedure 3: Query the wiki and file back the answer

1. Read the topic's Concept Index.md first, then locate articles: the index at small scale (< 30 articles), otherwise kb find <topic> "<question>" --explain, plus kb search or grep for exact terms. Answer from the wiki, never from general knowledge; a contradiction between the two is itself a finding.
2. Read the identified articles in full, following one level of [[wikilinks]] when relevant. Pull a raw source only to verify an ambiguous claim.
3. Answer with a [[wikilink]] citation for every factual claim, note agreements and disagreements between articles, and state gaps explicitly ("the wiki has no article on X"). Match the format to the question: prose, comparison table, numbered steps, Known / Open questions / Gaps, or a diagram (tooling-tips.md for Marp).
4. Save the answer to <topic>/outputs/queries/<YYYY-MM-DD> <Question Slug>.md (type: output, stage: query, informed_by: wikilinks) and call out insights to absorb on the next compile.
5. When the answer contradicts or extends an article, recompile it (Procedure 1). When the synthesis is durable (a comparison, a trade-off analysis, a new concept), promote it to wiki/concepts/ with Procedure 1 standards.
6. Append ## [YYYY-MM-DD] query | <Question Slug> (and ## [YYYY-MM-DD] promote | <Title> when promoted) to log.md.