A focused adaptation of Andrej Karpathy's llm-wiki pattern, narrowed to one audience: people who work with papers, equations, models, experiments, and code and who lean on AI — Claude Code, mainly — to do it.
This is an idea file. Paste it into your agent and build the wiki together. It describes the pattern; your agent fills in the specifics in collaboration with you. Everything here is the minimum that works — no future-proofing, no extras.
The usual setup is: drop a folder of papers into a tool, ask a question, the LLM retrieves a few relevant chunks and answers. It works, but nothing accumulates. Every question re-reads the raw sources from scratch. Ask something that needs five papers stitched together and the model re-finds and re-pieces those fragments every single time. Your understanding lives in chat logs that you'll never reopen.
Instead of re-retrieving at query time, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked set of markdown files sitting between you and the raw sources.
When you add a paper, the agent doesn't just index it. It reads it, extracts the method and results, and integrates it: updates the relevant concept pages, links it to papers it builds on or contradicts, notes where its assumptions differ from yours, and revises the running synthesis. The knowledge is compiled once and then kept current — not re-derived on every question.
You almost never write the wiki yourself. The LLM writes and maintains all of it. Your job is the part that needs a brain: choosing what to read, asking the hard questions, and deciding what it all means. The agent does the bookkeeping — summarizing, cross-referencing, filing, flagging contradictions — which is exactly the work humans abandon wikis over.
raw/ — your immutable sources. Paper PDFs, derivations, datasets, lab notes, code snippets, screenshots of figures. The agent reads from here and never edits it. This is your source of truth.
wiki/ — the LLM-generated markdown. Paper notes, concept and equation pages, model pages, an experiment log, an index, a synthesis. The agent owns this layer entirely: creates pages, updates them as sources arrive, keeps cross-references consistent. You read it; the agent writes it.
CLAUDE.md — the schema. One file telling Claude how the wiki is organized, what the conventions are, and what to do on ingest / ask / lint. This is what turns the agent into a disciplined wiki maintainer instead of a generic chatbot. You and the agent co-evolve it as you learn what works for your domain.
- Paper notes — one per source: the problem, the method, the headline result, the assumptions and regime of validity, the key equations (stated in your notation), and links to every concept and experiment it touches.
- Concept / equation pages — a derivation, a law, a method, written down once, cleanly, with consistent symbols, units, and limiting cases. Every paper and experiment that uses it links back here. This is the antidote to "wait, is it β or 1/β in this note?"
- Model pages — what the model assumes, where it holds and breaks, its inputs/outputs, and the papers and experiments that validate or stress it.
- Experiment log — one entry per run: what you ran, the parameters/seed/config, the result, which concept or claim it tests, and what it changed in your thinking. Reproducibility lives here.
- Synthesis / open questions — the evolving thesis: what's settled, what's contested across sources, what to read or run next.
Ingest. Drop a source into raw/ and tell Claude to process it. It reads, talks through the takeaways with you, writes a paper note, updates the index and log, and edits every concept/model/experiment page the source affects. A single paper might touch 10–15 pages. Prefer one at a time while you're learning the domain so you can guide what to emphasize.
Ask. Question the wiki, not the raw pile. Claude reads the index, opens the relevant pages, and answers with citations back to sources. The important move: good answers get filed back into the wiki as new pages — a derivation you worked out, a comparison table, a connection you spotted. Your explorations compound instead of vanishing into chat history.
Lint. Periodically ask Claude to health-check the wiki: contradictions between pages, claims a newer paper has superseded, concepts mentioned everywhere but lacking their own page, missing cross-links, orphan pages, gaps worth a literature search. Keeps it healthy as it grows.
index.md — content-oriented. A catalog of every page with a link and a one-line summary, grouped by type (papers, concepts, models, experiments). Updated on every ingest. Claude reads this first to find what's relevant, then drills in. At this scale (dozens to low hundreds of pages) the index alone is enough — no vector DB, no embedding pipeline, no RAG infrastructure.
log.md — chronological, append-only. One line per ingest / ask / lint, with a consistent prefix so it's greppable: ## [2026-06-04] ingest | Author et al. — Title. Gives you a timeline of how your understanding evolved and tells Claude what happened recently.
# Wiki maintenance instructions
You maintain a personal research wiki. Sources are in raw/ (read-only).
You own everything in wiki/. I curate sources and ask questions; you do all writing.
## Layout
- raw/ immutable sources (papers, data, notes, code) — never edit
- wiki/papers/ one note per source
- wiki/concepts/ equations, methods, definitions — stated once, canonical notation
- wiki/models/ model assumptions, validity, validation
- wiki/experiments/ one entry per run: params, seed, result, what it tests
- wiki/synthesis.md evolving thesis: settled / contested / open questions
- wiki/index.md catalog of all pages, grouped by type, one-line summaries
- wiki/log.md append-only timeline, prefix: ## [YYYY-MM-DD] <op> | <title>
## On INGEST <source>
1. Read it. Discuss key takeaways with me before writing.
2. Write wiki/papers/<slug>.md: problem, method, result, ASSUMPTIONS & regime
of validity, key equations (use canonical notation from wiki/concepts/), links.
3. Search existing wiki first. Edit + cross-link matching concept/model pages;
only create a new page when nothing fits.
4. Flag any contradiction with an existing claim explicitly — don't silently overwrite.
5. Update index.md and append to log.md.
## On ASK
- Read index.md, open relevant pages, answer with citations to raw/ sources.
- If the answer is reusable (a derivation, comparison, connection), offer to file it
as a new wiki page.
## On LINT
- Report: contradictions, superseded claims, orphan pages, concepts without a page,
missing cross-links, gaps worth a search. Suggest next sources/questions.
## Conventions
- Notation, symbols, and units are defined once in wiki/concepts/ and reused everywhere.
- Every quantitative claim traces to a paper or an experiment.
- Wikilinks between related pages. Keep pages tight and scannable.- Notation stated once. Symbols, units, and definitions are canonical and reused — no drift across forty scattered notes.
- Everything traces back. Every claim links to a paper or an experiment, so you can always check the source and the regime it assumed.
- Contradictions surface. When a new paper disagrees with an old one, it gets flagged, not buried.
- It compounds. Month three is richer than month one with no extra effort, because the maintenance cost is near zero — the agent doesn't get bored or forget to update a cross-reference.
mkdir -p raw wiki/papers wiki/concepts wiki/models wiki/experiments- Save the schema above as
CLAUDE.md; create emptywiki/index.mdandwiki/log.md. git init— the wiki is just markdown, so you get version history and branching for free.- Drop one paper into
raw/, open Claude Code, and say: "Ingest this source per CLAUDE.md." - Read what it writes, correct the notation and emphasis, then add the next source.
The schema is the only thing that needs tuning — co-evolve it with Claude as you go. Start with one paper; let it grow.