Obsidian Notes Karpathy

Review-gated, multi-agent-friendly Obsidian knowledge-base skills inspired by Karpathy-style markdown wikis and extended toward a creator-ready LLM Wiki workflow.

This bundle is aimed at users who may ask for an LLM Wiki, a Karpathy wiki, an Obsidian IDE for notes, a knowledge compiler, a personal knowledge base, or a markdown-first second brain without knowing the internal kb-* command names yet.

It also accepts the simpler Chinese-LLM-Wiki vocabulary. Requests phrased as 来源页, 主题页, 实体页, 综合页, output/analyses, or output/reports are translated onto the review-gated contract instead of forcing the repo back into a single-layer wiki.

raw/            -> immutable human + agent captures
raw/_manifest.yaml -> canonical source registry
MEMORY.md       -> collaboration memory and editorial context
outputs/episodes/ -> episodic memory / crystallized work arcs
wiki/drafts/    -> compiled draft knowledge
wiki/live/      -> approved long-term brain
wiki/live/topics/ -> approved browse-layer topic maps
wiki/live/procedures/ -> approved procedural memory
wiki/briefings/ -> role-specific context generated from live
outputs/        -> reviews, Q&A, health reports, audit logs, and publishable artifacts

The core idea is no longer just "compile notes into a wiki". It is "separate production from judgment so unreviewed drafts never become compound retrieval truth," and make compile itself strong enough to produce creator-ready knowledge assets.

Rust CLI

onkb is the deterministic Rust CLI for this bundle.

• normal lifecycle operations should use onkb directly
• skills remain the intelligent contract layer, but their baseline command is now onkb
• repo-local Python remains only as migration or repo-maintenance fallback while the Rust surface settles

Key commands:

• onkb version
• onkb doctor
• onkb --json status <vault-root>
• onkb --json ingest scan <vault-root>
• onkb --json compile scan <vault-root>
• onkb --json review queue <vault-root>
• onkb --json query scope <vault-root>
• onkb --json render <vault-root> --mode <mode> --source <path>

Skill set

• obsidian-notes-karpathy - lifecycle router
• kb-init - initialize, repair, or migrate a vault into the review-gated layout
• kb-ingest - register raw sources into raw/_manifest.yaml
• kb-compile - compile raw markdown captures into wiki/drafts/
• kb-review - approve, reject, or escalate drafts; rebuild wiki/briefings/
• kb-query - canonical read-side lane for search, grounded answers, archived Q&A reuse, and static web export from wiki/live/
• kb-render - deterministic slides, reports, charts, and canvas derivatives from approved knowledge

Companion skill matrix

The core bundle should own the review-gated lifecycle. Companion skills take over only for clearly external lanes such as paper PDFs or canvas-specific authoring.

For the vocabulary bridge from the simpler Chinese single-layer wiki model into this bundle's draft/live contract, see Chinese-LLM-Wiki Compatibility.

Contract highlights

• raw/ is immutable.
• treat raw/ as the durable source library; editorial notes, Q&A, and publish artifacts belong in downstream surfaces rather than mutating source captures.
• raw/_manifest.yaml is the canonical source registry for tracked inputs.
• MEMORY.md is collaboration memory, not retrieval truth.
• outputs/episodes/ stores episodic memory, not approved topic truth.
• kb-compile writes only to wiki/drafts/.
• raw paper PDFs under raw/**/papers/*.pdf remain a paper-workbench routing exception, not a normal kb-compile ingest.
• kb-review is the only promotion gate into wiki/live/.
• wiki/live/procedures/ is the procedural-memory lane for approved workflows and playbooks.
• wiki/live/topics/ is the browse-layer entry surface over approved knowledge clusters.
• wiki/briefings/ is generated from approved live pages only.
• kb-query reads wiki/live/, briefings, and prior Q&A, not drafts.
• outputs/audit/operations.jsonl is the machine-readable audit trail for automation and derived exports.
• legacy-layout vaults are detected and should be migrated before normal operation.
• alias alignment, source integrity, stale-page checks, and question tracking are absorbed as governance rules without collapsing the review gate.
• curated hubs and creator-planning surfaces may exist, but they remain navigation/maintenance layers rather than truth-boundary shortcuts.

Archive Surfaces

This bundle uses archive in two distinct senses:

• source retention archive - raw/** plus raw/_manifest.yaml
• artifact archive - durable downstream outputs under outputs/**

That split is intentional.

• The source retention archive means original captures stay retained and registered.
• It does not mean moving files into raw/09-archive/.
• The artifact archive is where durable answers, publish artifacts, episodes, review records, health reports, and static exports accumulate for reuse and maintenance.

The truth boundary stays the same:

• wiki/live/** = approved truth
• outputs/** = reusable archive surfaces
• archived outputs can trigger maintenance and writeback
• archived outputs do not become approved truth automatically

Why this is not a single-layer source/concept/synthesis wiki

This package deliberately does not treat a freshly generated wiki/ page as durable truth.

Instead:

• raw captures are first registered into raw/_manifest.yaml
• raw captures become reviewable drafts
• drafts become approved live notes only after kb-review
• query and publish work stay grounded in approved summaries and live pages
• health and reflection outputs surface governance work, but durable changes still re-enter draft -> review -> live

This keeps provenance visible and prevents fast ingest from silently hardening into long-term truth.

Karpathy alignment

This project implements Karpathy's LLM Wiki pattern with one key extension: an explicit review gate.

The core metaphor is preserved: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." The user curates sources and asks questions. The LLM handles all the bookkeeping that makes knowledge compound over time.

Required support vs optional outputs

The required support layer is raw/, wiki/drafts/, wiki/live/, wiki/briefings/, wiki/index.md, wiki/log.md, outputs/reviews/, AGENTS.md, and CLAUDE.md.

Downstream output surfaces are created when the later stages need them:

• outputs/qa/ - durable research answers from kb-query
• outputs/content/ - publish artifacts from kb-query
• outputs/slides/, outputs/reports/, and outputs/charts/ - deterministic derivative artifacts from kb-render
• outputs/web/ - static browseable exports from kb-query
• outputs/health/ - maintenance reports from kb-review maintenance mode
• MEMORY.md - recommended collaboration memory and editorial context

The archive posture across those surfaces is:

Optional governance indices such as wiki/live/indices/QUESTIONS.md, GAPS.md, and ALIASES.md may be created when the user wants richer maintenance surfaces.

Substantive answers and publish artifacts may also carry structured writeback candidates so later compile/review passes can decide whether they should feed back into the wiki. Candidates left at writeback_status: pending with followup_route: draft are picked up by onkb --json compile writeback <vault-root>, which scaffolds a reviewable draft grounded in the recorded approved pages and advances the status to drafted.

For creator-style workflows, a practical mapping is:

• source library / clipped research -> raw/
• web collection before raw intake -> web-access or Obsidian Web Clipper, then kb-ingest
• editorial memory -> MEMORY.md
• session crystallization -> outputs/episodes/
• reusable research answers or drafting notes -> outputs/qa/
• outward-facing publish artifacts -> outputs/content/
• durable approved knowledge -> wiki/live/
• durable approved workflows -> wiki/live/procedures/
• curated topic maps / planning surfaces -> wiki/live/indices/ or approved hub pages

Route ownership

• kb-init owns setup, repair, and legacy-layout migration.
• kb-ingest owns source registration, manifest refresh, and deferred intake surfacing.
• kb-compile owns raw-to-draft updates, including bootstrap raw/*.md captures.
• kb-review owns the governance lane: immediate draft promotion plus maintenance-mode drift checks, backlog pressure, provenance audits, alias drift, question/gap resurfacing, and safe mechanical fixes in approved surfaces only.
• kb-query reads approved live knowledge only and owns search, grounded answers, explicit publish mode, archived Q&A reuse, and static web export.
• kb-render owns deterministic derivatives from approved knowledge.

Deterministic helpers

Rust-first CLI surface:

• onkb version
• onkb doctor
• onkb --json doctor
• onkb skill install|list|show
• onkb --json status <vault-root>
• onkb --json init <vault-root> ...
• onkb --json migrate <vault-root> ...
• onkb --json ingest scan|sync <vault-root>
• onkb --json compile scan|build <vault-root>
• onkb --json compile writeback <vault-root> [--write]
• onkb --json review queue|lint|governance|indices|graph <vault-root>
• onkb --json query scope|rank <vault-root>
• onkb --json render <vault-root> --mode <mode> --source <path>

Compatibility and repo-maintenance scripts:

• skills/obsidian-notes-karpathy/scripts/skill-contract-registry.json
• onkb --json dev contract-validate
• onkb --json dev audit-skills
• onkb --json dev render-reference-block <skill>
• onkb --json dev eval-trigger [--dry-run] [--skill <name>]
• onkb --json dev eval-runtime [--dry-run] [--skill <name>] [--eval-id <id>] [--reuse-baseline-from <workspace>]

Skill contracts load references in two layers, both declared canonically in skill-contract-registry.json: a small unconditional core set (capped at 6 files per skill, enforced by dev contract-validate) plus on-demand references that each carry an explicit trigger condition in the SKILL's Load on demand section.

Install

cargo install --locked --git https://github.com/bahayonghang/obsidian-notes-karpathy.git onkb
onkb skill install

By default, onkb skill install installs the embedded runtime skills into the
current workspace only:

• .claude/skills
• .agents/skills

Additional local agent homes are explicit:

onkb skill install --cursor --windsurf --kiro --pi
onkb skill install --all-local

Global user-home installs are opt-in:

onkb skill install --global --claude --codex --gemini --agents

Use --overwrite to replace existing installed skill directories. Without it,
existing skill directories are skipped and reported in the JSON targets[]
payload. This command copies the embedded skills only; it does not write
bootstrap files, Cursor rules, or Kiro steering files.

For local development from a checked-out repo, use:

cargo install --path . --locked

If a skill step says onkb is not installed, use the GitHub install command above as the default fallback, then retry the same lifecycle command.

Docs site maintenance

The contributor docs site lives under docs/ and is built with VitePress.

• from the repo root, use just install, just docs, and just docs-build
• keep docs/package-lock.json committed when the docs toolchain changes
• the docs package uses npm overrides to keep transitive vite on a patched release line
• after changing docs dependencies, rerun npm audit and npm run build in docs/