The LLM-maintained Wiki — Karpathy's three-layer pattern

This is the pattern this very library — and the whole Atlas KB — runs on. Karpathy named it in April 2026 (gist 442a6bf). It is not a product or a library; it is a discipline for letting an LLM maintain a persistent, cross-linked markdown knowledge base on your behalf. We use it daily, so this article is both an explainer and an honest account of where it bites.

The one-sentence idea

Don't make the LLM re-derive answers from raw documents on every query (that's RAG). Instead, have it *compile* those documents once into a persistent, cross-linked wiki — and read from the compiled layer thereafter. The wiki compounds: every ingest and every good answer is filed back, so the knowledge base gets richer over time instead of resetting each session.

The mental model from the production write-ups is a cache hierarchy: the curated wiki is L1 (small, fast, always loaded into context); RAG over a giant corpus is L2 (large, slower, occasionally misses) [Atlan; decodethefuture]. Below a certain size you only need L1.

Why it matters

The insight Karpathy leans on is a division of labour:

"The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else."

And the "everything else" is precisely the part humans hate:

"The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping… LLMs don't get bored, don't forget to update a cross-reference."

That is the whole pitch. A human wiki rots because nobody updates the index, nobody fixes the dangling [[link]], nobody notices that page A now contradicts page C. An LLM does that bookkeeping tirelessly. You keep the judgement; you shed the clerical tax. It is, in effect, an agent-memory architecture (see [[agent-memory-systems]]): a durable, structured place an agent reads from and writes to across sessions, threads, and months — the unsolved problem of agentic AI made tractable with plain files.

How it works — the three layers

raw/      ← Layer 1: immutable source documents (you curate)
wiki/     ← Layer 2: LLM-compiled markdown (the LLM owns this entirely)
CLAUDE.md ← Layer 3: the schema (governs how the LLM behaves)

Layer 1 — Raw sources (immutable)

"Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them."

raw/ is the single source of truth. The LLM never edits it; it only reads. This matters for provenance: when a wiki page is wrong you can always re-derive it from an untouched source, and you always know what is primary (human-curated input) vs derived (LLM synthesis).

Layer 2 — The wiki (LLM-owned, cross-linked)

The LLM doesn't index sources for later retrieval — it integrates them:

"The LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki."

Page types: per-source summary pages, entity pages (a person, project, library, concept), concept pages, and synthesis/comparison documents. Everything is cross-linked with [[wikilinks]]. Two special files keep the wiki from rotting as it grows:

• `index.md` — "A catalog of everything in the wiki — each page listed with a link, a one-line summary." This is the LLM's map; without it the model re-scans the whole vault to orient itself, "burning tokens and sometimes missing files" [Fulkerson]. It is not optional at production scale.
• `log.md` — "An append-only record of what happened and when — ingests, queries, lint passes." The audit trail / episodic memory of the wiki itself.

Layer 3 — The schema (the real product)

A config document (Karpathy uses CLAUDE.md; the vendor-neutral name is AGENTS.md) that turns a generic LLM into a disciplined knowledge worker. It encodes the wiki's structure, naming conventions, page templates, and the exact workflows for the three operations below. The community consensus is blunt: the schema is the real product — it is where your domain knowledge, quality bar, and contradiction-handling rules live [v2 gist]. A good schema is what separates a tidy compounding wiki from a pile of LLM word-salad.

The three operations

Everything the LLM does to the wiki is one of three verbs.

1. Ingest. You drop a source into raw/. The LLM reads it, discusses the key takeaways with you (human in the loop, by design), writes a summary page, updates index.md, and updates every relevant entity and concept page. One source can legitimately touch 10–15 pages — that fan-out is the compounding. In prose-pseudocode:

on ingest(source):
    read(source)
    takeaways = discuss_with_human(source)     # not silent
    write(wiki/summaries/<source>.md, summary)
    for entity, concept in extract(takeaways):
        upsert(wiki/<entity-or-concept>.md)    # merge, don't duplicate
        add_crosslinks([[...]])
    append(index.md, one_line_catalog_entry)
    append(log.md, "ingest <source> @ <time>")

2. Query. You ask a question against the wiki (not against raw docs). The LLM searches relevant pages, reads them, and "synthesizes an answer with citations." The crucial twist: a good answer is filed back into the wiki — "This way your explorations compound in the knowledge base." The query path is itself a write path. Your questions become knowledge.

3. Lint. Periodic health checks — the bookkeeping that makes the whole thing work — looking for: "Contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references." This is the operation Karpathy's own early vault was missing; a practitioner who compared notes admitted "I had no vault-wide lint operation. No orphan detection, no broken link scanning, no stale content identification" [Fulkerson]. Lint is not a nicety — it is the thing that keeps a compounding store from compounding into contradiction.

Key ideas & tradeoffs

• Compile-once vs retrieve-every-time. RAG re-pays the synthesis cost on every query and never gets smarter. The wiki pays synthesis once at ingest and amortises it across all future reads. The tradeoff is freshness: a compiled fact is stale until re-ingested. (See [[graphrag]] for the retrieval-side cousin that builds a graph but still retrieves per query.)
• It only works small. The hard ceiling is ~50k–100k tokens (~150–200 dense pages) — roughly what fits in or near a context window. Below that line, direct file-reading is simpler, more reliable, and cheaper per query than any RAG pipeline. Above it, "there is no shortcut around the information-theoretic limits of context windows" [decodethefuture] — you must add semantic search. The smart move is hybrid: curated wiki as L1, RAG as L2 [Atlan].
• Provenance is a first-class concern. At scale you cannot tell human-curated truth from LLM guess by looking. The production fix is provenance tags in YAML frontmatter on every file, so the model (and you) know what is primary vs derived [Fulkerson]. Our library does exactly this with authored_by + sources:.
• Human-in-the-loop write gates are quality control, not backwardness. The most useful critique in the v2 thread came from a practitioner running it in production: event-driven auto-ingest corrupts wikis because "LLMs aren't reliable"; the discipline is "filter at ingest, explicit supersession (not decay), git as audit trail, manual before automated." The "discuss with you" step in ingest is not friction — it is the gate.

Honest caveats & limitations

This pattern is genuinely useful, and genuinely oversold in places. Being honest:

• The schema is most of the work, and nobody hands you a good one. "Just write a CLAUDE.md" hides the fact that a bad schema produces a confidently wrong wiki. The original gist gives the shape; it does not give you tested prompts, an entity-extraction spec, or a conflict-resolution algorithm. Those remain "an exercise" [v2 gist].
• v2's "memory lifecycle" additions are contested. The v2 gist proposes confidence scores, Ebbinghaus forgetting curves, and consolidation tiers (working→episodic→semantic→procedural). A production reviewer pushed back hard: numeric confidence is "false precision" vs an explicit chain of evidence, and "forgetting curves applied to errors repeat mistakes — old bugs matter." Treat lifecycle automation as a hypothesis, not settled practice. Explicit supersession + git history beats automatic decay for most real KBs.
• Auto-ingest at scale drifts. Static file-drops don't survive live operations; one production deployment ended up wiring 14 MCP servers of live data and a post-compact hook to re-inject critical state when the context window compressed mid-session [Fulkerson]. The clean three-layer diagram quietly grows a lot of plumbing in reality.
• It is not a search engine. Past ~200 pages the single index.md stops scaling and you need real retrieval (BM25 + vector + graph traversal fused by reciprocal-rank-fusion, per v2). At that point you are running a hybrid system, and the "no RAG needed" framing is no longer true.
• Compounding cuts both ways. A wrong fact filed back during a query propagates. Without disciplined lint, the same mechanism that makes the wiki smarter makes a polluted wiki confidently wrong. Lint frequency is a real operational parameter, not a footnote.

How it connects to OpenAlice

This is not a borrowed analogy — the Atlas KB you are reading is a Karpathy LLM-wiki, and we apply the three layers almost literally:

• The three layers map onto Atlas directly. knowledge/research/ and the ingested repos are our raw layer; the zoned markdown under knowledge/ (library/, learnings/, decisions/, architecture/, products/, lore/…) is the wiki layer; `ORG-CONVENTIONS.md` + each zone's `README.md` index + the auto-injected Atlas conventions are the schema — the rules every agent (and every subagent like this one) boots with. The per-zone README.md files are Karpathy's index.md; the weekly learnings/audit-2026-Wxx.md files are his log.md.
• Our three operations are his three operations. The keeper loop stated in this library's README — "ingest real sources → discuss the takeaways → write/refine a clear page → lint (no contradictions, stale claims, or orphans)" — is ingest/query/lint by another name. M12 (this educational library) and M13 (the [[deep-research]] skill: fan out Sonnet readers → synthesise Opus-level → write a cross-linked article) are the ingest pipeline made concrete; this very file was produced by it.
• Cron-refresh is our lint+ingest automation. Atlas re-ingests ~60 repos on a schedule and produces weekly digests — that is log.md and a partial vault-wide lint, automated. Per the production caveat above, we keep the human/agent in the loop for writes (agents author pages, NAO curates) rather than blind auto-ingest — exactly the "manual before automated, git as audit trail" discipline the practitioners recommend.
• We already do provenance frontmatter. Every library article carries sources:, authored_by, and date in YAML — the primary-vs-derived tagging the production write-up had to retrofit, we had from day one.
• The hybrid story is our story too. The curated KB is L1 (small, always loaded as agent context); Atlas's semantic search over 50k indexed symbols + pgvector is L2. "Query Atlas before grepping" is literally "read the compiled wiki before re-deriving from raw." Where the wiki is too big for context, we fall through to retrieval — the exact hybrid the sources prescribe.
• It is the substrate under agent memory. Each agent's MEMORY.md index + topic files (the convention NAO enforces across sessions) is a per-agent LLM-wiki: durable, indexed, cross-linked, compounding. The pattern is how Alice and the lab agents remember across sessions — see [[agent-memory-systems]] and [[mempalace]].

The related machinery in our world: [[graphify]] gives the call-graph/AST layer Atlas ingests; [[graphrag]] is the retrieval cousin for when the corpus outgrows a context window; [[model-routing]] decides which model does the ingest vs the synthesis; [[mixture-of-agents]] and [[fusion-and-llm-councils]] are how multiple models can co-author or review a wiki page. And the fundamentals trio — [[microgpt-build-an-llm-from-scratch]], [[llm-from-scratch]] — explain the engine that does the compiling in the first place.

Takeaways

1. Compile, don't retrieve — turn raw sources into a persistent cross-linked wiki once; read the compiled layer thereafter. It compounds.
2. Three layers: immutable raw/ · LLM-owned wiki/ (+ index.md map + log.md trail) · the schema that governs behaviour — and the schema is the real product.
3. Three verbs: ingest (fan a source into 10–15 pages, human in the loop) · query (answer with citations, file the answer back) · lint (kill contradictions, staleness, orphans, dangling links).
4. It only works small (~50k–100k tokens). Above that, go hybrid: wiki as L1, RAG as L2. There is no shortcut around the context-window limit.
5. Be honest: lifecycle auto-decay is contested, auto-ingest drifts, and a wiki without lint compounds into error. Keep writes gated, keep provenance tagged, keep git as the audit trail.
6. For us: the Atlas KB is this pattern. Our READMEs are index.md, our conventions are the schema, M12/M13 are the ingest pipeline, and "query Atlas first" is "read the compiled wiki first."

Part of the lab library (M12). Written by the M13 [[deep-research]] loop — itself an instance of the pattern it describes. Cross-links: [[fusion-and-llm-councils]] · [[microgpt-build-an-llm-from-scratch]] · [[llm-from-scratch]] · [[graphify]] · [[mempalace]] · [[mixture-of-agents]] · [[graphrag]] · [[agent-memory-systems]] · [[model-routing]].