---
name: llm-knowledge-base
description: >
  Build and maintain a Karpathy-style LLM knowledge base — a persistent, compounding wiki
  of interlinked markdown files that an LLM compiles from raw sources and maintains over time.
  Use when: (1) creating a new knowledge base on any topic, (2) ingesting a new source document
  into an existing knowledge base, (3) querying a knowledge base for synthesized answers,
  (4) running a lint/health-check on a knowledge base, (5) setting up Obsidian integration for
  viewing. Triggers on phrases like "build a knowledge base", "create a wiki", "ingest this into
  the KB", "lint the knowledge base", "research and compile", "Karpathy wiki".
---

# LLM Knowledge Base

Build persistent, compounding knowledge bases where an LLM compiles raw sources into a
structured wiki of interlinked markdown files. The human curates sources and asks questions;
the LLM does all the writing, cross-referencing, and maintenance.

## Three Layers

```
knowledge-base/
├── CLAUDE.md              ← Schema (conventions, workflows, page format)
├── topic-name/
│   ├── raw/               ← Immutable source documents (never modify)
│   └── wiki/
│       ├── index.md       ← Content catalog with one-line summaries
│       ├── log.md         ← Chronological ingest/query/lint log
│       └── *.md           ← Wiki articles (LLM-owned)
```

- **raw/** — Source of truth. Articles, papers, notes, data. LLM reads but never modifies.
- **wiki/** — LLM's domain. Summaries, entity pages, concept pages, synthesis. LLM creates and maintains everything.
- **CLAUDE.md** — Schema file telling the LLM how to structure and maintain the wiki.

## Page Format

Every wiki page must have:

```markdown
---
title: Page Title
tags: [topic, relevant, tags]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# Page Title

Content...

## See Also
- [[related-page|Display Name]] — one-line description
```

Use `[[wikilinks]]` (Obsidian format). YAML frontmatter on every page. `## See Also` at bottom.

## Four Workflows

### 1. Ingest (new source added to raw/)
1. Read the new source document thoroughly
2. Write or update a summary page in wiki/
3. Update ALL relevant entity/concept pages (one source may touch 5-15 pages)
4. Update index.md with new/changed pages
5. Append entry to log.md
6. Flag contradictions with existing content

### 2. Query (human asks a question)
1. Read the topic's index.md first
2. Identify and read relevant wiki pages
3. Synthesize answer with citations to wiki pages
4. If answer is valuable, file it as a new wiki page
5. Append query entry to log.md

### 3. Lint (periodic health check)
1. Check for contradictions between pages
2. Find orphan pages (no inbound links)
3. Find concepts mentioned but lacking their own page
4. Check for stale data that newer sources supersede
5. Verify frontmatter consistency (title, tags, dates)
6. Suggest new questions to investigate
7. Append lint entry to log.md

### 4. Update (periodic refresh)
1. Review recent raw/ additions not yet ingested
2. Check if any wiki pages reference outdated data
3. Update frontmatter `updated` dates on changed pages
4. Rebuild index.md if needed

## Setup: New Knowledge Base

To create a new knowledge base from scratch:

```bash
# 1. Create directory structure
mkdir -p ~/knowledge-base/TOPIC/{raw,wiki}

# 2. Create CLAUDE.md schema (copy from references/schema-template.md)
cp SCHEMA_TEMPLATE ~/knowledge-base/CLAUDE.md

# 3. Create initial index.md and log.md
# 4. Initialize git repo
cd ~/knowledge-base && git init && git add -A && git commit -m "Initial knowledge base"

# 5. Push to GitHub (private repo recommended)
gh repo create USERNAME/knowledge-base --private --source=. --push
```

## Setup: Obsidian Integration

For viewing the wiki in Obsidian:

1. Clone the repo on your local machine
2. Open the folder as an Obsidian vault
3. Install "Obsidian Git" plugin for auto-pull
4. Graph view colors by topic (configure in `.obsidian/graph.json`)
5. Recommended plugins: Dataview (frontmatter queries), Marp (slide decks)

## Delegation to Claude Code

For heavy maintenance (lint, bulk ingest), delegate to Claude Code:

```bash
bash -i -c 'cd ~/knowledge-base && claude --print --permission-mode bypassPermissions \
  --model "$ANTHROPIC_MODEL" "Read CLAUDE.md. Then lint all topics and fix issues. \
  Git commit and push when done."'
```

## Key Principles

- Raw sources are IMMUTABLE — never modify files in raw/
- Wiki pages are the LLM's domain — create, update, restructure freely
- Always update index.md when adding/changing pages
- Always append to log.md for any action
- Prefer many focused pages over few large pages
- Cross-reference aggressively — links are as valuable as content
- The wiki is a git repo — version history for free

## References

- See `references/schema-template.md` for the full CLAUDE.md template
- Based on [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)