agent-docs

kevin-wiki — working here

Purpose

Kevin's personal LLM Wiki (Karpathy pattern): flat markdown files, no vector DB, schema-as-readable. Three layers — immutable raw/ sources, the LLM-written wiki/ knowledge base, and AGENTS.md (the schema). Kevin curates sources and asks questions; the agent does the summarizing, cross-referencing, filing, and bookkeeping.

Mental model & key files

  • AGENTS.md — the full schema, conventions, and operations guide. Read first.
  • wiki/ — compiled knowledge (you own this). wiki/_index.md is the catalog; wiki/RESOLVER.md is the filing tree; wiki/SOUL.md / USER.md / HEARTBEAT.md are identity. wiki/meta/agent-operations-hub.md is the routing map.
  • raw/ — immutable source material (read, never modify).
  • scripts/ — tsx maintenance CLIs (see scripts/SKILL.md).
  • ui/ — the Next.js viewer (see ui/SKILL.md).
  • config/ + skills/ — agent config + skill taxonomy, symlinked into ~/.cursor/~/.claude.

Patterns to follow / invariants

  • Brain-first: qmd search/qmd query before any external lookup.
  • Quality: every fact carries an inline [Source: ...]; every entity mention is back-linked; compiled truth is rewritten, the timeline is append-only.
  • Use rg, never grep. Tests use node:test via tsx.
  • No one-off work: if it'll recur, codify it as a skill or automation.

Common tasks → first action

  • Start a session → read SOUL/USER/HEARTBEAT + the hub, then npx tsx scripts/check-freshness.ts.
  • Ingest a source / "add it" → wiki/meta/capture-ingest-protocol.md (full graph, not one file).
  • After wiki edits → npx tsx scripts/build-index.ts then qmd update && qmd embed.
  • Health check → npx tsx scripts/doctor.ts.

Gotchas

  • Never hand-author a ## Backlinks section — backlinks are computed.
  • _index.md and README's stats table are generated — don't edit by hand.
  • Don't propagate clone-folder suffixes (e.g. my-wiki-real) into prose; the project is kevin-wiki everywhere.