LLM Wiki — Second Brain for Claude Code + Obsidian
Inspired by Andrej Karpathy's LLM Wiki pattern (gist). This skill turns Claude Code (or any agent CLI) into a disciplined wiki maintainer that incrementally builds and maintains a persistent, interlinked Obsidian vault as you feed it sources. The knowledge compounds — cross-references, contradictions, and synthesis are already there when you query.
Core principle
Most LLM+docs workflows are RAG: retrieve fragments at query time, synthesize from scratch, forget. The wiki is compounding: sources are read once, integrated into a persistent markdown knowledge base, and kept current. You curate and ask; the LLM reads, files, cross-references, and maintains.
Obsidian is the IDE. The LLM is the programmer. The wiki is the codebase.
When to use
- Personal: track goals, health, psychology, journaling, self-improvement
- Research: deep dives over weeks on a topic — papers, articles, reports, evolving thesis
- Book companion: file chapters as you read; build a fan-wiki-style companion for characters, themes, plot threads
- Business/team: internal wiki fed by Slack, meeting notes, calls — LLM does maintenance nobody else wants to do
- Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives
Do NOT use when: you need one-shot Q&A over a fixed document (use RAG), you don't plan to add sources over time, or you don't want Obsidian in the loop.
Architecture (three layers)
vault/
├── raw/ # Layer 1 — IMMUTABLE source of truth
│ ├── <source files> # Articles, papers, PDFs, images, data
│ └── assets/ # Downloaded images from clipped articles
├── wiki/ # Layer 2 — LLM-owned knowledge base
│ ├── index.md # Content catalog (LLM updates every ingest)
│ ├── log.md # Append-only timeline (## [YYYY-MM-DD] <op> | <title>)
│ ├── entities/ # Person/Org/Place pages
│ ├── concepts/ # Ideas, theories, frameworks
│ ├── sources/ # One summary page per ingested source
│ ├── comparisons/ # Cross-source analysis pages
│ └── synthesis/ # High-level syntheses, theses, overviews
├── CLAUDE.md # Schema + conventions (Claude Code)
└── AGENTS.md # Same content, for Codex/Cursor/Antigravity
- Layer 1 (raw/) — you own. LLM only reads; never writes.
- Layer 2 (wiki/) — LLM owns. It creates, updates, and cross-references pages. You read it.
- Layer 3 (CLAUDE.md / AGENTS.md) — the schema. Conventions, workflows, frontmatter rules. Co-evolved by you and the LLM.
Three core operations
- Ingest — LLM reads a source, discusses takeaways with you, writes a source summary, updates 10-15 relevant pages, updates index, appends to log. See
references/ingest-workflow.md.
- Query — LLM reads
index.md first, drills into relevant pages, synthesizes with citations. Good answers get filed back into the wiki so explorations compound. See references/query-workflow.md.
- Lint — Health check: contradictions, stale claims, orphan pages, missing cross-refs, concepts mentioned but lacking their own page, data gaps to fill with web search. See
references/lint-workflow.md.
Quick start
# 1. Initialize a vault (in Obsidian's vault directory)
python scripts/init_vault.py --path ~/vaults/research --topic "LLM interpretability"
# 2. Drop a source into raw/, then ingest
/wiki-ingest ~/vaults/research/raw/anthropic-monosemanticity.pdf
# 3. Ask questions (answers can be re-filed into the wiki)
/wiki-query "how does monosemanticity compare to mechanistic interpretability?"
# 4. Periodic health check
/wiki-lint
# 5. See the timeline
/wiki-log --last 10
Slash commands (this plugin ships)
| Command |
Purpose |
/wiki-init |
Bootstrap a fresh vault with schema files + starter structure |
/wiki-ingest <path> |
Read a source, discuss, update wiki, log it |
/wiki-query <question> |
Search wiki, synthesize answer, offer to file back |
/wiki-lint |
Run health check — contradictions, orphans, stale claims, gaps |
/wiki-log |
Show recent log entries (uses unix tools on log.md) |
Sub-agents (this plugin ships)
| Agent |
When dispatched |
wiki-ingestor |
Delegated ingest flow — reads source, proposes updates, applies after your approval |
wiki-linter |
Runs the health-check workflow independently, reports findings |
wiki-librarian |
Answers queries using index-first search, synthesizes with citations |
Python tools (scripts/)
All tools are standard library only (no pip installs). Run with python scripts/<tool>.py --help.
| Script |
Purpose |
init_vault.py |
Create folder structure + seed CLAUDE.md, AGENTS.md, index.md, log.md |
ingest_source.py |
Helper: extract text/frontmatter from a source file, ready for LLM review |
update_index.py |
Regenerate index.md from wiki page frontmatter (category, date, source count) |
append_log.py |
Append a standardized log entry ## [YYYY-MM-DD] <op> | <title> |
wiki_search.py |
BM25 search over wiki pages (standalone fallback when index.md isn't enough) |
lint_wiki.py |
Find orphans (no inbound links), stale pages, missing cross-refs, broken links |
graph_analyzer.py |
Compute link graph stats — hubs, orphans, clusters, disconnected components |
export_marp.py |
Render a wiki page (or subtree) to a Marp slide deck |
Cross-tool compatibility
The vault's schema lives in CLAUDE.md (Claude Code) or AGENTS.md (Codex/Cursor/Antigravity/OpenCode). The same content works in both. This plugin ships both templates. For per-tool setup instructions see references/cross-tool-setup.md.
CLAUDE.md → Claude Code
AGENTS.md → Codex CLI, Cursor, Antigravity, OpenCode, Gemini CLI
.cursorrules → legacy Cursor (pre-AGENTS.md)
The scripts are pure Python stdlib → run identically everywhere. Only the loader file changes per tool.
Obsidian setup (recommended)
- Obsidian Web Clipper — browser extension; converts web articles to markdown and drops them in
raw/
- Download images locally — Settings → Files and links → Attachment folder path =
raw/assets/. Settings → Hotkeys → bind "Download attachments for current file" to Ctrl+Shift+D
- Graph view — see hubs/orphans; essential for spotting structural problems
- Marp plugin — Markdown-based slide decks directly from wiki pages
- Dataview plugin — dynamic tables/lists over page frontmatter (tags, dates, source counts)
- Git — the vault is a plain markdown repo; version it
Full setup walkthrough: references/obsidian-setup.md
Why this works (vs plain RAG)
| Plain RAG |
LLM Wiki |
| Rediscover knowledge each query |
Knowledge accumulates |
| Cross-references re-computed every time |
Cross-references pre-written and maintained |
| Contradictions surface only if you ask |
Contradictions flagged during ingest |
| Exploration disappears into chat history |
Good answers re-filed as new pages |
| Scales by embeddings infrastructure |
Scales by markdown + index.md + optional local search |
At ~100 sources / hundreds of pages, index.md + filesystem search is enough. Past that, layer in a local search tool like qmd or use scripts/wiki_search.py.
Related skills (chains via context: fork)
This skill is marked context: fork so other skills can chain into it:
para-memory-files — PARA-method memory; complementary as long-term personal memory that feeds sources into the wikiobsidian-vault (mattpocock) — lightweight Obsidian note helper; this skill is the maintained-wiki layer on toprag-design — when wiki outgrows ~500 pages, use rag-design to bolt on a retrieval layermcp-design — expose the wiki as an MCP toolagent-communication — for multi-agent wiki maintenance (ingestor + linter + librarian)
Reference docs
references/wiki-schema.md — full vault layout, page frontmatter, naming conventionsreferences/page-formats.md — entity, concept, source, comparison, synthesis templatesreferences/ingest-workflow.md — the detailed ingest flow the wiki-ingestor agent followsreferences/query-workflow.md — query patterns, citation format, re-filing answersreferences/lint-workflow.md — health-check heuristicsreferences/obsidian-setup.md — Obsidian plugins, hotkeys, vault configreferences/cross-tool-setup.md — per-tool setup (Codex, Cursor, Antigravity, etc.)references/memex-principles.md — Bush's Memex, why the LLM changes the maintenance math
Templates (assets/)
CLAUDE.md.template, AGENTS.md.template, .cursorrules.template — schema loaders per toolindex.md.template, log.md.template — starter index and logpage-templates/ — entity, concept, source-summary, comparison, synthesisexample-vault/ — small worked example you can study or copy
Iron rule
The LLM never edits files in raw/. Ever. Sources are immutable. All LLM writes go to wiki/. If you need to correct a source, do it in raw/ yourself — then re-ingest.
Activation Triggers
Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
1---2name: llm-wiki3description: Use when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current.4license: MIT5---67# LLM Wiki — Second Brain for Claude Code + Obsidian89Inspired by Andrej Karpathy's LLM Wiki pattern ([gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)). This skill turns Claude Code (or any agent CLI) into a disciplined wiki maintainer that **incrementally builds and maintains** a persistent, interlinked Obsidian vault as you feed it sources. The knowledge compounds — cross-references, contradictions, and synthesis are already there when you query.1011## Core principle1213Most LLM+docs workflows are **RAG**: retrieve fragments at query time, synthesize from scratch, forget. The wiki is **compounding**: sources are read once, integrated into a persistent markdown knowledge base, and kept current. You curate and ask; the LLM reads, files, cross-references, and maintains.1415> Obsidian is the IDE. The LLM is the programmer. The wiki is the codebase.1617## When to use1819- **Personal**: track goals, health, psychology, journaling, self-improvement20- **Research**: deep dives over weeks on a topic — papers, articles, reports, evolving thesis21- **Book companion**: file chapters as you read; build a fan-wiki-style companion for characters, themes, plot threads22- **Business/team**: internal wiki fed by Slack, meeting notes, calls — LLM does maintenance nobody else wants to do23- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives**2425**Do NOT use when:** you need one-shot Q&A over a fixed document (use RAG), you don't plan to add sources over time, or you don't want Obsidian in the loop.2627## Architecture (three layers)2829```30vault/31├── raw/ # Layer 1 — IMMUTABLE source of truth32│ ├── <source files> # Articles, papers, PDFs, images, data33│ └── assets/ # Downloaded images from clipped articles34├── wiki/ # Layer 2 — LLM-owned knowledge base35│ ├── index.md # Content catalog (LLM updates every ingest)36│ ├── log.md # Append-only timeline (## [YYYY-MM-DD] <op> | <title>)37│ ├── entities/ # Person/Org/Place pages38│ ├── concepts/ # Ideas, theories, frameworks39│ ├── sources/ # One summary page per ingested source40│ ├── comparisons/ # Cross-source analysis pages41│ └── synthesis/ # High-level syntheses, theses, overviews42├── CLAUDE.md # Schema + conventions (Claude Code)43└── AGENTS.md # Same content, for Codex/Cursor/Antigravity44```4546- **Layer 1 (raw/)** — you own. LLM only reads; never writes.47- **Layer 2 (wiki/)** — LLM owns. It creates, updates, and cross-references pages. You read it.48- **Layer 3 (CLAUDE.md / AGENTS.md)** — the *schema*. Conventions, workflows, frontmatter rules. Co-evolved by you and the LLM.4950## Three core operations51521. **Ingest** — LLM reads a source, discusses takeaways with you, writes a source summary, updates 10-15 relevant pages, updates index, appends to log. See `references/ingest-workflow.md`.532. **Query** — LLM reads `index.md` first, drills into relevant pages, synthesizes with citations. Good answers get **filed back into the wiki** so explorations compound. See `references/query-workflow.md`.543. **Lint** — Health check: contradictions, stale claims, orphan pages, missing cross-refs, concepts mentioned but lacking their own page, data gaps to fill with web search. See `references/lint-workflow.md`.5556## Quick start5758```bash59# 1. Initialize a vault (in Obsidian's vault directory)60python scripts/init_vault.py --path ~/vaults/research --topic "LLM interpretability"6162# 2. Drop a source into raw/, then ingest63/wiki-ingest ~/vaults/research/raw/anthropic-monosemanticity.pdf6465# 3. Ask questions (answers can be re-filed into the wiki)66/wiki-query "how does monosemanticity compare to mechanistic interpretability?"6768# 4. Periodic health check69/wiki-lint7071# 5. See the timeline72/wiki-log --last 1073```7475## Slash commands (this plugin ships)7677| Command | Purpose |78|---|---|79| `/wiki-init` | Bootstrap a fresh vault with schema files + starter structure |80| `/wiki-ingest <path>` | Read a source, discuss, update wiki, log it |81| `/wiki-query <question>` | Search wiki, synthesize answer, offer to file back |82| `/wiki-lint` | Run health check — contradictions, orphans, stale claims, gaps |83| `/wiki-log` | Show recent log entries (uses unix tools on `log.md`) |8485## Sub-agents (this plugin ships)8687| Agent | When dispatched |88|---|---|89| `wiki-ingestor` | Delegated ingest flow — reads source, proposes updates, applies after your approval |90| `wiki-linter` | Runs the health-check workflow independently, reports findings |91| `wiki-librarian` | Answers queries using index-first search, synthesizes with citations |9293## Python tools (`scripts/`)9495All tools are **standard library only** (no pip installs). Run with `python scripts/<tool>.py --help`.9697| Script | Purpose |98|---|---|99| `init_vault.py` | Create folder structure + seed CLAUDE.md, AGENTS.md, index.md, log.md |100| `ingest_source.py` | Helper: extract text/frontmatter from a source file, ready for LLM review |101| `update_index.py` | Regenerate `index.md` from wiki page frontmatter (category, date, source count) |102| `append_log.py` | Append a standardized log entry `## [YYYY-MM-DD] <op> \| <title>` |103| `wiki_search.py` | BM25 search over wiki pages (standalone fallback when index.md isn't enough) |104| `lint_wiki.py` | Find orphans (no inbound links), stale pages, missing cross-refs, broken links |105| `graph_analyzer.py` | Compute link graph stats — hubs, orphans, clusters, disconnected components |106| `export_marp.py` | Render a wiki page (or subtree) to a Marp slide deck |107108## Cross-tool compatibility109110The vault's **schema** lives in CLAUDE.md (Claude Code) or AGENTS.md (Codex/Cursor/Antigravity/OpenCode). The same content works in both. This plugin ships both templates. For per-tool setup instructions see `references/cross-tool-setup.md`.111112```113CLAUDE.md → Claude Code114AGENTS.md → Codex CLI, Cursor, Antigravity, OpenCode, Gemini CLI115.cursorrules → legacy Cursor (pre-AGENTS.md)116```117118The scripts are pure Python stdlib → run identically everywhere. Only the loader file changes per tool.119120## Obsidian setup (recommended)121122- **Obsidian Web Clipper** — browser extension; converts web articles to markdown and drops them in `raw/`123- **Download images locally** — Settings → Files and links → Attachment folder path = `raw/assets/`. Settings → Hotkeys → bind "Download attachments for current file" to `Ctrl+Shift+D`124- **Graph view** — see hubs/orphans; essential for spotting structural problems125- **Marp plugin** — Markdown-based slide decks directly from wiki pages126- **Dataview plugin** — dynamic tables/lists over page frontmatter (tags, dates, source counts)127- **Git** — the vault is a plain markdown repo; version it128129Full setup walkthrough: `references/obsidian-setup.md`130131## Why this works (vs plain RAG)132133| Plain RAG | LLM Wiki |134|---|---|135| Rediscover knowledge each query | Knowledge accumulates |136| Cross-references re-computed every time | Cross-references pre-written and maintained |137| Contradictions surface only if you ask | Contradictions flagged during ingest |138| Exploration disappears into chat history | Good answers re-filed as new pages |139| Scales by embeddings infrastructure | Scales by markdown + `index.md` + optional local search |140141At ~100 sources / hundreds of pages, `index.md` + filesystem search is enough. Past that, layer in a local search tool like [qmd](https://github.com/tobi/qmd) or use `scripts/wiki_search.py`.142143## Related skills (chains via `context: fork`)144145This skill is marked `context: fork` so other skills can chain into it:146147- **`para-memory-files`** — PARA-method memory; complementary as long-term personal memory that feeds sources into the wiki148- **`obsidian-vault`** (mattpocock) — lightweight Obsidian note helper; this skill is the maintained-wiki layer on top149- **`rag-design`** — when wiki outgrows ~500 pages, use rag-design to bolt on a retrieval layer150- **`mcp-design`** — expose the wiki as an MCP tool151- **`agent-communication`** — for multi-agent wiki maintenance (ingestor + linter + librarian)152153## Reference docs154155- `references/wiki-schema.md` — full vault layout, page frontmatter, naming conventions156- `references/page-formats.md` — entity, concept, source, comparison, synthesis templates157- `references/ingest-workflow.md` — the detailed ingest flow the wiki-ingestor agent follows158- `references/query-workflow.md` — query patterns, citation format, re-filing answers159- `references/lint-workflow.md` — health-check heuristics160- `references/obsidian-setup.md` — Obsidian plugins, hotkeys, vault config161- `references/cross-tool-setup.md` — per-tool setup (Codex, Cursor, Antigravity, etc.)162- `references/memex-principles.md` — Bush's Memex, why the LLM changes the maintenance math163164## Templates (`assets/`)165166- `CLAUDE.md.template`, `AGENTS.md.template`, `.cursorrules.template` — schema loaders per tool167- `index.md.template`, `log.md.template` — starter index and log168- `page-templates/` — entity, concept, source-summary, comparison, synthesis169- `example-vault/` — small worked example you can study or copy170171## Iron rule172173**The LLM never edits files in `raw/`.** Ever. Sources are immutable. All LLM writes go to `wiki/`. If you need to correct a source, do it in `raw/` yourself — then re-ingest.174175## Activation Triggers176177Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
JantonioFC