Karpathy’s LLM Wiki is a 3-layer architecture — raw sources, LLM-compiled markdown pages, and a schema file — that replaces stateless RAG with a persistent, self-maintaining knowledge base. Instead of retrieving and re-synthesizing documents on every query, the LLM “compiles” them once into cross-referenced wiki pages, then reads from the compiled layer at query time. The pattern works best for personal knowledge bases under ~100 000 tokens and runs on plain markdown plus any coding agent (Claude Code, Codex, Cursor).
What Is an LLM Wiki and Why Does It Matter?
In April 2026 Andrej Karpathy — founding member of OpenAI, former head of AI at Tesla — published a GitHub gist that collected over 5 000 stars in its first week. The idea: stop treating retrieval-augmented generation (RAG) as the default way to give an LLM access to your documents, and instead let the model maintain a structured, cross-referenced wiki for you.
Most developers’ experience with LLMs and documents looks the same — upload files, embed chunks into a vector database, retrieve the top-k at query time, generate an answer. It works, but the model rediscovers knowledge from scratch on every question. There is no accumulation. Ask something that requires synthesizing five documents, and the LLM has to find and stitch the relevant fragments together every single time.
Karpathy’s insight is that the expensive part of maintaining a knowledge base is not reading or thinking — it is the bookkeeping: cross-references, summaries, deduplication, conflict resolution. Those are exactly the tasks LLMs are disproportionately good at, and humans reliably abandon after two weeks. The LLM Wiki pattern flips the workload: the model handles maintenance, the human handles curation and judgment.
How Does the 3-Layer Architecture Work?
The pattern consists of three clearly separated layers. Understanding them is the difference between a system that compounds and a folder of markdown that rots.
Layer 1 — Raw Sources
Immutable input documents: PDFs, articles, papers, screenshots, bookmarks, voice transcripts. They live in a raw/ directory and are never modified after ingestion. Think of this as the “source of truth” archive. Every wiki page eventually traces back here.
Layer 2 — The Wiki
LLM-generated markdown files stored in a wiki/ directory. Each file is an “article” — a concept page, an entity page, a comparison, a timeline. The model creates these by reading raw sources and distilling them into a consistent internal format: title, summary, tagged topics, body, backlinks. Over time, the wiki becomes a densely interlinked knowledge graph written in natural language.
Layer 3 — The Schema
A configuration document (Karpathy uses CLAUDE.md, but any agent-readable format works) that tells the LLM what the wiki is about, which conventions to follow, and how to handle conflicts. This is the equivalent of an editorial style guide for the model. Without it, the wiki drifts — pages become inconsistent, naming conventions fragment, cross-references break.
The diagram shows how the three layers stack. The LLM agent sits between the schema and the wiki, reading the schema for conventions, writing to the wiki during ingest, and reading from the wiki during queries. Raw sources feed into the wiki once and are never touched again. Three operations — ingest, query, lint — cycle through this stack.
What Are the 3 Core Operations: Ingest, Query, Lint?
Ingest — compile once, use forever
When you add a new source document, the LLM reads it end to end, then updates every relevant wiki page — potentially 10–15 files in a single pass. It creates new concept pages where needed, adds cross-references, updates index.md (the master table of contents), and appends a chronological entry to log.md. This is the “compilation step.” The cost is paid once; every subsequent query benefits from the compiled output.
Query — read the compiled layer
When you ask a question, the LLM loads index.md first — a lightweight map of the entire wiki — then pulls the specific articles it needs. Because the knowledge is already structured and cross-referenced, the model can answer multi-document questions without re-embedding or re-retrieving anything. If the wiki fits in context (under ~100k tokens), retrieval reliability is effectively 100%: every page is available, no chunk is missed.
Lint — periodic health check
Over time any wiki develops inconsistencies. The lint operation scans for contradictions between pages, orphaned articles with no inbound links, missing backlinks, factual drift (source says X, wiki says Y), and coverage gaps. Think of it as a CI/CD pipeline for knowledge. Karpathy recommends running it weekly or after large ingestion batches.
The ingest step is where most token cost concentrates. A 10-page PDF might trigger updates across 12 wiki files. Budget roughly 5–8× the source token count for a full ingest pass. Subsequent queries against the compiled wiki are far cheaper — typically just index.md + 2–3 article pages.
How Does LLM Wiki Compare to RAG?
The comparison is not “one replaces the other.” Each pattern wins in a specific regime. The table below captures the trade-offs that matter for architecture decisions.
| Dimension | LLM Wiki | RAG (Vector DB) |
|---|---|---|
| Knowledge state | Persistent, compiled, accumulates | Stateless — re-retrieved per query |
| Retrieval reliability | ~100% (everything in context) | Depends on embedding quality, chunking, top-k |
| Scale ceiling | ~50k–100k tokens (~150–200 pages) | Millions of documents |
| Infrastructure | Plain files + any coding agent | Vector DB, embedding pipeline, retrieval API |
| Per-query token cost | Fixed (wiki loaded each time) | Variable (only retrieved chunks) |
| Multi-doc synthesis | Excellent — cross-references pre-built | Depends on retrieval recall across docs |
| Maintenance burden | LLM handles bookkeeping | Re-indexing, chunk tuning, embedding drift |
| Vendor lock-in | Zero — plain markdown files | Tied to vector DB + embedding model |
| Best for | Personal research, focused domains | Enterprise search, large corpora, real-time data |
The 50k–100k token threshold is where the LLM Wiki stops being practical. Below that line the direct file-reading approach is simpler, more reliable, and cheaper per query than a RAG pipeline. Above it, you need semantic search — there is no shortcut around information-theoretic limits of context windows.
The smartest teams are moving toward a hybrid: stable, curated knowledge compiled into a wiki (loaded as system context or in the first turn), plus RAG for dynamic, large, or frequently-changing data. The wiki acts as “L1 cache” — fast, always available. RAG acts as “L2” — larger, slower, occasionally misses.
How Do You Build an LLM Wiki From Scratch?
Let’s build one. The implementation below uses Claude Code as the agent, but the pattern works with any coding agent that can read and write local files — Codex CLI, Cursor, OpenCode. The total setup takes about 15 minutes.
Step 1 — Create the directory structure
mkdir -p my-wiki/{raw,wiki}
touch my-wiki/wiki/index.md
touch my-wiki/wiki/log.md
touch my-wiki/CLAUDE.mdThree directories, three seed files. raw/ holds your source documents. wiki/ holds the LLM-generated pages. CLAUDE.md is the schema — the editorial guide for the model.
Step 2 — Write the schema (CLAUDE.md)
This is the most important file in the system. A weak schema produces a weak wiki. Here is a production-ready template:
# My Research Wiki — Schema
## Purpose
Personal knowledge base on [YOUR TOPIC].
This wiki is maintained by an LLM agent. Humans curate sources
and ask questions. The agent handles all bookkeeping.
## Conventions
- One concept = one file in wiki/
- Filenames: lowercase, hyphens, no spaces (e.g. transformer-architecture.md)
- Every wiki page starts with: # Title, then a 2-sentence summary,
then ## Tags, then the body
- Cross-reference related pages using [[page-name]] wikilinks
- When sources conflict, note the conflict explicitly and cite both
## Index rules
- wiki/index.md lists every page: `- [[page-name]]: one-line description`
- Keep index.md sorted alphabetically
- Update index.md on EVERY ingest or page creation
## Log rules
- wiki/log.md is append-only, newest first
- Format: `## YYYY-MM-DD — [source filename]`
then a bullet list of changes made
## Ingest procedure
1. Read the new source in raw/ end to end
2. Identify key concepts, entities, claims
3. For each: create or update the relevant wiki page
4. Add/update cross-references ([[wikilinks]])
5. Update index.md
6. Append to log.md
## Lint checklist
- [ ] Every page in wiki/ appears in index.md
- [ ] Every [[wikilink]] resolves to a real file
- [ ] No two pages cover the same concept
- [ ] Conflicting claims are flagged, not silently overwrittenStep 3 — Ingest your first source
Drop a document into raw/, then tell your agent to ingest it. With Claude Code:
Read raw/attention-is-all-you-need.pdf and ingest it into the wiki
following the schema in CLAUDE.md. Create or update all relevant
wiki pages, cross-references, index, and log.The agent will typically create 3–8 new wiki pages from a single dense paper: one for the core concept (self-attention), one for the architecture (transformer), entity pages for key authors, a page for related benchmarks. Each gets wikilinks to the others. The index updates. The log records what happened.
Step 4 — Query the wiki
Using the wiki, explain how multi-head attention differs from
single-head attention and which papers introduced each variant.
Cite specific wiki pages.The agent reads index.md, identifies relevant pages, loads them, and synthesizes an answer with citations back to your wiki pages (which themselves cite the original sources). Two-hop traceability: answer → wiki page → raw source.
Step 5 — Run lint
Run a full lint of the wiki per the checklist in CLAUDE.md.
Report issues and fix what you can automatically.Since every page is plain markdown with wikilinks, Obsidian renders it as a navigable graph out of the box. Open the wiki/ folder as an Obsidian vault — you get clickable backlinks, a visual graph view, and full-text search for free. Git provides version history automatically.
What Does It Cost? Token Economics of Ingest vs. Query
The token arithmetic is what makes this pattern either brilliant or impractical, depending on your scale. Let’s run the numbers on a real scenario: a research wiki with 80 compiled pages averaging 500 tokens each — about 40 000 tokens total.
Ingest cost: Adding a 10-page PDF (~8 000 tokens) triggers updates across ~12 wiki pages. The agent reads the full source, reads each target page, writes updated versions, and updates the index and log. Total ingest cost: roughly 40 000–60 000 tokens (input + output). This cost is paid once per source.
Query cost: The agent loads index.md (~2 000 tokens for an 80-page wiki), plus 2–4 relevant pages (~1 000–2 000 tokens), plus generates a response (~500–1 000 tokens). Total per query: ~4 000–5 000 tokens. Compare that to a RAG pipeline retrieving 5 chunks at 500 tokens each plus embedding overhead — similar ballpark, but with 100% recall instead of best-effort retrieval.
The break-even point: If you query a topic more than 8–10 times, the upfront ingest cost has been amortized. For topics you revisit daily — active research areas, ongoing projects — the economics are strongly in the wiki’s favor. For a one-off question about a document you will never look at again, plain RAG or even just stuffing the document into context is faster and cheaper.
Where Does the LLM Wiki Pattern Break Down?
Karpathy scoped the pattern explicitly to individual researchers. That scoping is honest and important. Here are the failure modes:
Scale ceiling. At ~100 000 tokens the wiki no longer fits in a single context window. You can mitigate this with a two-tier approach — load only the index plus targeted pages — but at some point you are reinventing RAG with extra steps. If your corpus is genuinely large (thousands of documents, millions of tokens), you need a vector database. There is no architectural shortcut.
Multi-user access. The pattern assumes a single curator. There is no merge resolution, no access control, no concurrent editing protocol. Two people running ingest on the same wiki will produce conflicting edits. For teams, you need either a coordination layer (git branches + review) or a proper shared knowledge system.
Epistemic drift. The LLM generates wiki pages. Those pages become the knowledge the LLM reads on future queries. If the model introduces a subtle error during ingest — a misinterpretation, a hallucinated connection — that error compounds. Every subsequent ingest that touches the affected page may reinforce it. The lint operation mitigates this but does not eliminate it. Human review of wiki edits (via git diffs) is the real safety net.
Real-time data. The wiki is a compiled artifact. It reflects the state of knowledge at the last ingest. If your sources change hourly — stock prices, live feeds, sensor data — the wiki is always stale. RAG against a live database is the right tool here.
Model dependency. While the files themselves are plain markdown (zero vendor lock-in on the data layer), the quality of the wiki depends on the model that maintains it. A model upgrade might change how pages are written; a model downgrade might miss nuances. The schema in CLAUDE.md provides some stability, but it is not a substitute for model capability.
What Does This Mean in Practice? 7 Hard-Won Lessons
Having tested this pattern extensively on a research wiki tracking machine learning architecture papers and a personal finance knowledge base, here are the lessons that are not in the gist:
1. The schema is 80% of the outcome. A vague CLAUDE.md produces a vague wiki. Invest a full hour in writing precise conventions — naming patterns, summary format, how to handle conflicts, when to create a new page vs. append to an existing one. This hour pays for itself within the first week.
2. Keep raw sources immutable — no exceptions. The moment you start editing files in raw/, you lose the ability to trace wiki claims back to their source. If a source has errors, note the correction in the wiki page with a citation, do not fix the original.
3. Git is non-negotiable. Every ingest produces a diff. Reviewing those diffs is how you catch epistemic drift early. A simple git diff wiki/ after each ingest takes 30 seconds and prevents compounding errors.
4. Index.md is the performance bottleneck. If your index grows past ~3 000 tokens, the agent spends too many tokens just reading the map. Split into sub-indexes by topic area: index-ml.md, index-finance.md, with a master index pointing to sub-indexes.
5. Lint weekly, not monthly. Orphaned pages and broken wikilinks accumulate faster than you expect. Weekly lint keeps the wiki navigable. Monthly lint means a cleanup session that takes an hour.
6. The hybrid is the endgame. For anything under 50k tokens, pure wiki wins. For 50k–200k tokens, wiki index + selective page loading. For 200k+ tokens, add semantic search (qmd, ripgrep, or a lightweight embedding index) on top of the wiki structure. The wiki does not replace RAG — it replaces the unstructured mess that people feed into RAG.
7. Obsidian is the best viewer, but any markdown renderer works. The graph view in Obsidian lets you see the shape of your knowledge base — clusters of densely linked pages, isolated orphans, missing connections. It turns the abstract concept of “knowledge structure” into something visual and actionable. VS Code with a markdown preview works too; you just lose the graph.
How Does the LLM Wiki Fit Into AI Data Governance Under the EU AI Act?
The EU AI Act (Regulation 2024/1689), now in its phased enforcement through 2026, places significant requirements on documentation and traceability for AI systems — especially those classified as high-risk. While a personal LLM Wiki is unlikely to trigger high-risk classification on its own, the pattern’s architecture aligns well with the Act’s emphasis on data governance.
Specifically, the three-layer separation gives you built-in traceability: every wiki claim traces to a specific raw source document, every change is logged in log.md, and the schema documents the rules the AI follows. If you are building AI agents that rely on organizational knowledge bases — and those agents inform decisions in regulated domains — this paper trail is not optional. The wiki’s git-backed history, combined with the immutable raw source archive, provides the kind of provenance that compliance teams increasingly demand.
For developers building knowledge-grounded AI systems inside EU-regulated organizations, the LLM Wiki pattern offers a practical starting point for the “data governance measures” described in Article 10 — not because it was designed for compliance, but because good knowledge engineering and good governance turn out to require the same things: clear provenance, explicit rules, and auditable change logs.
FAQ
No. The LLM Wiki replaces RAG for personal or small-team knowledge bases under ~100 000 tokens. For large-scale enterprise corpora, frequently changing datasets, or multi-user systems, RAG remains the right architecture. The strongest approach for mid-scale use cases is a hybrid: a compiled wiki for stable core knowledge, plus RAG for dynamic or overflow content.
Any agent that can read and write local files works: Claude Code (Anthropic), Codex CLI (OpenAI), Cursor, OpenCode, and others. The pattern is agent-agnostic — the wiki is plain markdown, so switching agents requires no data migration. Karpathy’s gist specifically mentions Claude Code, Codex, and OpenCode as compatible options.
The practical ceiling is around 50 000–100 000 tokens for a single-context approach, which translates to roughly 150–200 pages of dense text. Beyond that, you need to introduce selective page loading (only load index.md plus relevant pages) or add a lightweight search layer. At 200k+ tokens, semantic search becomes necessary.
CLAUDE.md is the schema file — an editorial style guide that the LLM agent reads before performing any operation on the wiki. It defines naming conventions, page structure, cross-referencing rules, conflict-resolution policies, and the lint checklist. The quality of the schema directly determines the quality and consistency of the wiki over time.
Yes — this is called epistemic drift. If the LLM misinterprets a source during ingest, the error becomes part of the wiki and can influence future ingests. The mitigations are: regular lint operations, human review of git diffs after each ingest, and maintaining immutable raw sources so you can always verify claims against the originals.
Notion AI and Mem add AI features to proprietary note-taking platforms. The LLM Wiki is an open architectural pattern — plain markdown files, no vendor lock-in, no subscription. You own the data entirely. The trade-off is that the wiki requires initial setup and a coding agent to maintain, while Notion AI and Mem offer a polished UI out of the box. For developers and researchers who value data ownership and customization, the wiki pattern is more powerful.
You need to be comfortable with a terminal and basic file operations (creating directories, moving files). You do not need to write code — the coding agent handles all file creation, editing, and cross-referencing. The schema (CLAUDE.md) is written in plain English. Viewing the wiki in Obsidian requires no coding at all.