Personal knowledge base maintained by agents. Based on Karpathy's LLM Wiki, with ideas from Farza's Personal Wiki.

Flat Markdown in wiki/, no database, the schema is readable not just queryable. Local search: qmd (BM25 + vectors on-device, no API keys). The authoritative schema is AGENTS.md at repo root — read that for the full contract; this README is the human-facing tour.

---

Table of contents

• Mental model · The three layers · Repository stats
• Quick start · Repository layout
• The knowledge base · Page format & conventions · Identity & routing files
• Agent discovery pipeline
• Search (qmd) · Source capture & ingest
• Automations · Skills · Agent config & rules
• Health: doctors & self-heal · Integrations & recipes
• Cross-agent integration · The viewer (ui) · Plans
• Maintenance cheat-sheet · Keeping this README honest · Credits

---

Mental model

The wiki is the codebase; the LLM is the programmer. Kevin curates sources, directs analysis, and asks questions. The agent does everything else — summarizing, cross-referencing, filing, bookkeeping. Kevin reads the wiki; the agent writes it and never makes Kevin edit pages by hand.

His primary capture path is pasting a URL, post, or repo into chat and saying add it — agents then run the full integration pipeline in wiki/meta/capture-ingest-protocol.md (primary page + entity pages + backlinks + citations + routing + index + search + log), never a one-off stub. Obsidian (or any Markdown reader) is optional for browsing.

The wiki is a compounding artifact: cross-references are already there, contradictions already flagged, synthesis already reflects everything ingested. Knowledge is compiled once and kept current, not re-derived per query. Kevin should never have to remember what is stale — that is the agent's job (see health).

The three layers

Memory routing: facts about the world → wiki/; rules about how the agent should operate → config/ (agent rules); facts about the current conversation only → nothing persisted.

Repository stats

The table above is machine-generated between the markers by npm run build-index — never hand-edit it. Run npm run wiki-status for a live category breakdown, orphans, tag histograms, and absorption rate.

Quick start

Prerequisites: Node.js 20+ and npm. qmd for local search. pnpm for the ui/ viewer. Optional per-integration credentials (see recipes).

npm install

# Symlink agent config from this repo -> ~/.cursor and ~/.claude
# (installs git hooks and validates generated skill/runtime links)
npm run setup

# Session health: overdue automations, stale syncs, self-heal nudge
npm run status                      # = npx tsx scripts/check-freshness.ts

# Rebuild catalog + backlinks + refresh the stats table above
npm run build-index

# Regenerate executable skill registry + flat runtime skill index
npm run skill-registry

# Regenerate portable agent doc packs from wiki capsules
npm run agent-packs

# Validate / score the local agent self-improvement eval suite
npm run agent-self-eval

# Refresh capability snapshots: skills, MCPs, CLIs, patterns, source feeds
npm run harvest:capabilities

# Local hybrid search index (after wiki edits)
qmd update && qmd embed

# System health score (wiki structure, skills, rules, automations, config)
npx tsx scripts/doctor.ts

# Routing and portable pack checks
npm run routing-doctor

# Wiki viewer (Next.js)
npm run dev                         # → http://localhost:3000

Repository layout

kevin-wiki/
├── AGENTS.md            Schema — operations, page format, automations, skills (Codex/Claude/Cursor read this)
├── CLAUDE.md            Points to AGENTS.md (Claude Code entry)
├── .cursorrules         Points to AGENTS.md (Cursor entry)
├── state.json           Last-run timestamps for syncs / automations / maintenance
├── raw/                 Immutable sources — obsidian, x-bookmarks, ai-sessions, registries, google, calendar, email, meetings, calls
├── wiki/                Compiled knowledge base (agents own this) — see The knowledge base
├── agents/              File-native agent contracts — tools, skills, subagents, schedules, evals
├── evals/               Deterministic agent eval suites and receipt fixtures
├── agent-docs/          Portable generated workflow packs compiled from wiki capsules
├── automations/         Recurring agent tasks (markdown prompts + Cursor cloud companions)
├── skills/              Executable SKILL.md taxonomy — categorized source + generated flat runtime index
├── config/
│   ├── cursor/          Cursor rules, hooks, mcp.json, cli-config (bootstrap symlink source)
│   └── dedalus/         Dedalus monorepo rules/hooks/agents reference mirror
├── scripts/            TypeScript CLIs — ingest, sync, index, lint, doctor, self-heal, MCP/voice servers
│   ├── lib/            Shared helpers (state, absorb-log, integration DB, triage, …)
│   └── agent-docs/     Agent-Docs Mesh kit (scaffold AGENTS.md + per-dir SKILL.md, docs-doctor)
├── recipes/            Integration installer docs (calendar, email, meetings, ngrok, voice)
├── plans/             Drained implementation specs for cheaper models to execute (borrowed-intelligence)
├── docs/              Long-form specs and design docs (e.g. superpowers specs)
├── outputs/           Automation outputs (gitignored, ephemeral)
└── ui/                Next.js App Router wiki viewer + /me portfolio

Run npm run bootstrap on any new machine to wire config/ and skills/ into ~/.cursor and ~/.claude via symlinks.

The knowledge base (wiki/)

wiki/ is a flat tree of Markdown files organized into 25 top-level categories. Each category directory has a README.md resolver describing what belongs there. The master catalog wiki/_index.md lists every page (regenerated by build-index).

Counts drift as the wiki grows; the canonical totals are the stats table. Key index/bookkeeping files:

• wiki/_index.md — content catalog of every page (auto-generated)
• wiki/_backlinks.json — typed reverse-link graph (auto-generated; rendered by the viewer)
• wiki/log.md — append-only chronological operations journal (## [YYYY-MM-DD] op | title)
• wiki/_absorb_log.json — which raw sources have been compiled into which pages
• wiki/RESOLVER.md — filing decision tree (read before creating any page)
• wiki/meta/ — meta-knowledge about the wiki itself (the operations hub, capture protocol, doctor history, discovery index, llms.txt)

Page format & conventions

Every page carries YAML frontmatter and follows a compiled-truth + timeline shape:

---
title: Page Title
type: concept | person | project | tool | skill | design | architecture | …
created: YYYY-MM-DD
updated: YYYY-MM-DD
source: path/or/url
tags: [tag1, tag2]
related: ["[[Other Page]]"]
aliases: ["Alt name", "handle@x"]   # required for person pages
tier: 1 | 2 | 3                      # enrichment priority
---

# Page Title

> One-line summary of what this page is about.

{Compiled truth — current synthesis, organized by theme, REWRITTEN as evidence changes}

---

## Timeline
- **YYYY-MM-DD** | What happened. [Source: who, channel, date]   # APPEND-only

Enforced conventions (full detail in AGENTS.md and config/cursor/rules/):

• Citations (mandatory): every fact carries an inline [Source: …]. Hierarchy: Kevin's direct statements > primary sources > API data > web search. Conflicts are flagged, not silently resolved.
• Back-link iron law: every mention of an entity that has a page creates a reverse link from that entity's page. An unlinked mention is a broken wiki.
• Compiled truth vs timeline: the section above --- is rewritten with the current best understanding; the timeline below is append-only (corrections are new dated entries, never deletions).
• Entity identity: search aliases before creating a page; merge duplicates; kebab-case.md slugs are the stable identity.
• Tiers: tier: 1 (core — full enrichment on every signal) → tier: 3 (passing mention).
• Length follows content: stubs under ~15 lines get merged; genuinely long reference pages opt in with longform: true.

Identity & routing files

Agents read these in order at the start of every session:

Agent discovery pipeline

Agents do not load the whole wiki, all skills, and every tool manifest up front. They walk a staged discovery pipeline: boot docs establish identity and rules, capsules choose the right context bundle, routers decide the narrowest execution path, and skills/tools do the work.

The layers are intentionally separate:

Capsules are the conceptual clusters. Generated packs are the portable files an agent can load. Routers still choose the exact action; packs do not replace routers, because a design task may need design.md, but the router still decides whether that means taste, frontend-design, browser-qa, figma, or qmd.

Self-improving agents use the same discovery pipeline plus receipts: agents/codex-self-improver/ defines the file-native contract, evals/agent-self-improvement/ defines the benchmark, and npm run agent-self-eval validates or scores a run receipt.

Current generated pack catalog (65 packs) lives in wiki/agent-docs/README.md and is emitted to agent-docs/packs/:

Regeneration rules are boring on purpose: edit the canonical wiki page or scripts/generate-agent-packs.ts, then run npm run agent-packs and npm run agent-packs:check. Do not hand-edit agent-docs/packs/*.md; they are compiled output, not source.

Search (qmd)

The wiki is indexed locally by qmd — BM25 + vector + query expansion + LLM re-ranking, all on-device via GGUF models. No API keys, no cloud.

qmd search "keyword"      # BM25 — fast, exact matches
qmd vsearch "concept"     # semantic (vector)
qmd query "question"      # hybrid + rerank — best quality
qmd get wiki/path.md      # direct document read
qmd update && qmd embed   # incremental re-index after edits

Brain-first rule: search the wiki before reaching for web/API on any question about Kevin's people/tools/concepts. qmd also exposes an MCP server (query, get, multi_get, status) configured in config/cursor/mcp.json; serve it remotely with npm run serve (see recipes/ngrok-tunnel.md).

Source capture & ingest

Two intake paths feed raw/, then agents compile into wiki/ per capture-ingest-protocol.md.

X bookmarks have a deeper path: scripts/enrich-x-bookmarks.ts resolves t.co links, fetches destinations (README/article/transcript), captures self-threads and author artifact replies, and writes raw/x-bookmarks/enriched/*.json before absorption. Daily source-compile uses those records for online research, wiki updates, and skill/tool routing. After compiling any source, agents call markAbsorbed() (scripts/lib/absorb-log.ts); pending sources surface in npm run wiki-status.

Automations

Task definitions live in automations/, each as a Markdown prompt with a frontmatter contract. Slugs with a *.cursor-automation.md companion can run in Cursor Automations (cloud cron); Codex-local schedules live under ~/.codex/automations; anything else can run manually in an agent session. Examples: signal-radar, frontend-frontier-radar, source-compile, capability-harvest, scheduling-audit, career-pipeline, project-briefing, self-heal, calendar-sync, email-sync, meeting-sync.

npm run automation:list                 # list all definitions
npm run automation -- <slug>            # scaffold a run (writes to outputs/<date>/<slug>/)
npm run automation:compare -- <slug>    # merge + diff multi-agent outputs

Each scheduled run writes to the gitignored outputs/, applies wiki_targets only when promotion criteria pass, updates state.json, and appends to wiki/log.md. If no durable update is warranted, the output says so explicitly. Full schedule + runner matrix: AGENTS.md § Automations, automations/_schema.md, and wiki/meta/scheduling-operating-model.md.

Skills

Executable agent procedures live in category buckets under skills/, then npm run skill-registry projects them into the flat runtime index used by Cursor, Claude Code, Codex, and AgentSkills:

~/.agents/skills is the universal bridge. Most harnesses read it directly; harnesses with bespoke skill dirs should symlink or point those dirs to ~/.agents/skills rather than copying skills.

Skills-first rule: before any specialized task, check for an installed or skills.sh skill rather than hand-rolling. Wiki sync (enforced): executable skills live under category folders, while wiki/meta/skill-registry.{json,md}, wiki/concepts/*-skills.md, generated wiki/skills/<category>/ source views, and skills/.runtime/all provide compact cross-agent discoverability. scripts/sync-skills.sh --check runs in bootstrap and the pre-commit hook.

Noisy imported families are compacted into parent router skills. For example, aws, azure, firebase, gws, stitch, posthog, sentry, clerk, cloudflare, tanstack, stripe, supabase, terraform, vercel, nextjs, taste, pixel-art, rust, and vue remain discoverable as single executable routes, while their child prompts live under references/skills/<old-slug>/SKILL.md for progressive disclosure. Use npm run skills:compact after adding or importing a related family, then npm run skill-registry and npm run skills:check.

Create skills with the skill-creator skill, then refresh the generated registry. The superpowers plugin (brainstorming, writing-plans, systematic-debugging, TDD, verification) is always enforced.

Agent config & rules

config/ is the canonical source for agent configuration; npm run bootstrap symlinks it into the live tool directories (so editing ~/.cursor/rules/foo.mdc edits config/cursor/rules/foo.mdc).

config/cursor/
├── rules/         .mdc rules — a few brief always-on, the rest agent-requested / auto-attached
├── hooks/         beforeShellExecution / event hooks (e.g. git-guard.sh)
├── hooks.json     hook registration
├── mcp.json       MCP servers (qmd, plugins)
└── cli-config.json
config/dedalus/     Dedalus monorepo rules / hooks / agents reference mirror

• Always-on rules (every message, kept lean): brain-first, quality, test-before-bulk, no-one-off-work, ripgrep, process-hygiene, agent-docs-mesh, signal-detector, wiki-source-of-truth.
• On-demand rules (fetched when relevant): tool-hierarchy.mdc (ranked tool registry), agent-native-cli.mdc, pr-review-lessons.mdc, last30days-research.mdc, agent-reach.mdc, ideation-paradigms.mdc.
• Git safety: config/cursor/hooks/git-guard.sh gates destructive git ops; uncommitted work you did not author is never discarded (use a worktree for parallel agents).
• Agent-Docs Mesh: scripts/agent-docs/ scaffolds a root AGENTS.md + per-directory SKILL.md in any repo and runs a docs-doctor.

Health: doctors & self-heal

The wiki keeps itself honest with a detection → healing loop (the doctor pattern + self-maintaining systems).

npm run status                       # check-freshness: overdue automations, stale syncs, self-heal nudge
npx tsx scripts/doctor.ts            # 5 sub-doctors → 0-100 health score + trend (wiki/meta/doctor-history.json)
npx tsx scripts/doctor.ts --min-score 90   # CI gate
npm run self-heal                    # triage doctor findings, selective digest (read-only)
npm run self-heal -- --apply         # apply provably-safe fixes, re-run doctor to verify
npm run routing-doctor               # routing structure + behavior (check-resolvable + trigger-eval + audit-rule-typing)
npx tsx scripts/lint.ts              # compatibility alias for doctor.ts --only wiki

• doctor.ts scores five subsystems — wiki structure, skills, rules, automations, config-sync — on unique-rule weighting (100 − 1.5·errors − 0.75·warns), tracks the trend, and exits non-zero below a --min-score floor.
• self-heal.ts closes the loop: it triages every doctor finding into auto-safe / agent-fix / escalate / noise, remembers per-finding dispositions in wiki/meta/self-heal-state.json so handled findings stand down, applies the deterministic safe fixes, verifies by re-running the doctor, and notifies selectively. The self-heal automation does the content fixes behind a PR and escalates destructive ones.

Integrations & recipes

External data flows in via self-contained installer docs in recipes/ (7 recipes). Collectors write to raw/; agents compile into wiki/. Shared state lives in PGlite at ~/.kevin-wiki/integrations.pglite (dedup IDs, cursors, sync timestamps, OAuth tokens).

Remote MCP access (Claude Desktop, Perplexity, any MCP client) is served over HTTP with bearer auth by npm run serve / npm run serve:remote.

Cross-agent integration

One wiki, every tool — the schema is the single source of truth across agents:

The viewer (ui/)

A Next.js App Router app under ui/ renders the Markdown wiki with sidebar navigation, search, a backlink graph, OG images, and a /me portfolio. Build-time scripts (ui/scripts/) bundle wiki content and enforce inline citations + gate passwords.

npm run dev      # cd ui && pnpm dev → http://localhost:3000
npm run build    # pnpm --dir ui install --frozen-lockfile && build

See ui/SKILL.md and ui/package.json for framework versions.

Plans

plans/ is a catalog of drained implementation specs — the borrowed-intelligence pattern: plan with the strongest model now, hand a self-contained spec to a cheaper model (or a later session) to execute via the agent-iteration loop. Pairs with the improve skill, which surveys a codebase read-only and emits prioritized specs.

Maintenance cheat-sheet

# Session start
npm run status                       # what's stale / overdue / needs attention

# Wiki integrity
npm run build-index                  # rebuild _index.md + _backlinks.json + README stats table
npx tsx scripts/build-discovery.ts   # regenerate discovery-index.json + llms.txt
npx tsx scripts/doctor.ts            # full health score
npm run self-heal -- --apply         # triage + safe auto-fixes + verify
npm run wiki-status                  # pages, tags, orphans, absorption rate
npm run wiki-breakdown               # mine pages for missing-page candidates

# Config
npm run bootstrap                    # re-sync agent config + skill runtime symlinks
npm run skill-registry               # regenerate skill registry, source views, runtime index
npm run agent-packs:check            # verify generated capsule packs are fresh
npm run skills:check                 # validate skill taxonomy ↔ wiki pages

After substantive wiki edits: build-index → qmd update && qmd embed → append wiki/log.md.

Keeping this README honest

• The Repository stats table is overwritten only by npm run build-index (between the auto markers) — never hand-edit it.
• Agents should update the narrative sections here whenever the repo layout, primary workflows, automation set, scripts, or conventions change materially — the same bar applied to wiki/log.md and AGENTS.md cross-checks. See wiki/meta/capture-ingest-protocol.md and wiki/meta/agent-operations-hub.md.

Credits

Authored and maintained by Kevin Liu (@Kevin-Liu-01).

Built on:

• Karpathy LLM Wiki
• Farza Personal Wiki
• qmd — on-device hybrid search
• fieldtheory — X bookmarks sync