The LLM-Wiki Pattern

Andrej Karpathy's pattern for personal knowledge bases: rather than retrieving from raw documents at query time, an LLM incrementally compiles and maintains a persistent wiki that sits between you and your sources. Published Apr 2026 as a gist; ingested here 2026-07-20 from llm-wiki-karpathy (source).

This is the pattern BRAIN.md implements, so this page serves two jobs: state the pattern as its author does, and record where this vault deviates. The deviations are the useful part — the gist is deliberately abstract and expects instantiation.

The core claim: compiled, not re-derived

The contrast is with RAG. Upload files, retrieve chunks per query, generate an answer — it works, but "the LLM is rediscovering knowledge from scratch on every question. There's no accumulation." A question needing five documents synthesised re-does that synthesis every time, and the result evaporates into chat history.

The alternative inverts when the work happens. On ingest, the LLM reads the source and integrates it — updating entity pages, revising summaries, noting where new data contradicts old claims. By query time the cross-references already exist and the contradictions are already flagged. Karpathy's framing: "the wiki is a persistent, compounding artifact."

The division of labour is strict and is the point: you source, explore, and ask; the LLM does "the summarizing, cross-referencing, filing, and bookkeeping." You never write the wiki yourself. His working setup is the agent on one side and Obsidian on the other — "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."

Three layers

Layer	Owner	Rule
Raw sources	you	immutable — the LLM reads, never modifies. Source of truth.
The wiki	the LLM, entirely	markdown pages: summaries, entities, concepts, synthesis. You read it.
The schema	co-evolved	the config doc (CLAUDE.md / AGENTS.md) defining structure, conventions, workflows.

The schema layer carries the most weight. Karpathy calls it "the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot," and stresses that you and the LLM co-evolve it as you learn what your domain needs. It is not setup; it is the ongoing artifact.

Three operations

• Ingest — read the source, discuss takeaways with the human, write a summary page, update the index, update affected pages, append to the log. Karpathy expects "a single source might touch 10-15 wiki pages," and prefers ingesting one at a time while staying involved, over unsupervised batch ingestion.
• Query — search, read, synthesise with citations. The load-bearing insight: "good answers can be filed back into the wiki as new pages" — a comparison, an analysis, a discovered connection. Explorations compound exactly like sources do.
• Lint — periodic health check: contradictions, stale claims superseded by newer sources, orphan pages, concepts mentioned but lacking a page, missing cross-references, gaps a web search could fill.

Two navigation files

Deliberately separate, and the distinction survives into BRAIN.md:

• index.md is content-oriented — a catalog by category, each page with a one-line summary. Read first on any query, then drill in. Karpathy claims this "works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure." That claim is examined at length in agent-memory-at-scale.
• log.md is chronological — append-only, what happened when. The tip is to give every entry a consistent prefix so the file stays greppable with plain unix tools.

Why it works

The argument is about cost, not capability:

The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Humans abandon wikis because the maintenance burden grows faster than the value.

LLMs "don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass." Maintenance cost approaches zero, so the wiki survives.

He places this against Vannevar Bush's Memex (1945) — a private, curated store with associative trails between documents, where the links matter as much as the documents. Bush's vision was closer to this than to what the web became. The part he couldn't solve was who does the maintenance.

Tooling (all optional)

• qmd — on-device search over markdown, hybrid BM25 + vector with LLM re-ranking. Ships both a CLI (shell out) and an MCP server (native tool). Named as the upgrade for when index.md alone stops sufficing.
• Obsidian Web Clipper for capture; graph view to see hubs and orphans.
• Marp for slide-deck output; Dataview for querying page frontmatter.
• Download images locally so links can't rot. Caveat worth knowing: LLMs can't read markdown with inline images in one pass — read the text first, then view images separately.
• The wiki is a git repo, so version history and branching come free.

How this vault instantiates it

Gist	This vault
the schema (CLAUDE.md/AGENTS.md)	BRAIN.md — loaded by both Claude Code and Claude Desktop; wins over background memory on conflict
raw sources, immutable	sources/ + sources/assets/
the wiki	wiki/topics/, wiki/entities/, wiki/assets/
index.md	wiki/index.md, plus a growth frontier section listing unresolved wikilinks
log.md	journal/<year>/<yyyy-mm-dd>.md
ingest / query / lint	/ingest, /wikify, /lint skills — thin dispatchers onto BRAIN.md

Where this vault diverges

1. Memory is an addition, not part of the pattern. The gist has no memory/ concept at all — it describes one system, a wiki fed by external sources. This vault runs two: memory (memory/, journal/) for what happened, wiki for what's known, explicitly never merged. That split is Wim's, and it does real work the pattern doesn't address: session-derived project decisions have no source document to ingest, so under the pure pattern they'd have nowhere to live.

2. log.md became per-day journal files. A direct trade: per-day files stay small and are trivially addressable by date, but they break the gist's stated benefit — grep "^## \[" log.md | tail -5 assumes one file. The vault recovers this with consistent line prefixes (ingest |, query |, lint |) that stay greppable across files, so the capability survives; only the one-file form is lost.

3. The /wikify operation has no equivalent in the gist. It is the explicit form of what Karpathy folds into Query's "file good answers back" — promoted here to a named operation for sessions with no external source at all.

Not yet matched: the "10-15 wiki pages per source" expectation. Ingests here have touched one to three pages. Either the vault is still too small for a source to ripple, or cross-linking is under-aggressive — agent-memory-at-scale argues each link is a retrieval path that survives index truncation, which makes under-linking a real cost rather than a stylistic one. Worth watching as a /lint signal.

The frontmatter question — resolved 2026-07-20

The gist, this vault, and OKF held three different positions on the same question:

• The gist suggests it optionally — "if your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables." Tooling convenience, nothing more.
• BRAIN.md forbade it — "no frontmatter" in Writing conventions, and "Never frontmatter" again under tag placement. Metadata went into a ## Tags section at the bottom, drawn from a closed vocabulary.
• OKF mandates it — type is its one required field, and frontmatter is the interoperability surface.

They were less contradictory than they looked, because they answer different questions: Dataview convenience, authoring discipline, machine parseability.

Wim resolved this in favour of OKF's schema on 2026-07-20. BRAIN.md now requires frontmatter on wiki pages, sources, and the index files. Two findings made the old rule cheaper to drop than it appeared:

• Its replacement had no reader. The ## Tags channel sat at 8 of 17 pages with five tags outside the declared vocabulary — and nothing in the vault read tags at all. Every mention across BRAIN.md and the skills was a writing rule.
• The gap to conformance was one field, not the metadata block the rule was guarding against.

The closed vocabulary went with it. Tags are free-form now, and /lint reports singleton tags and near-synonyms instead of a list rejecting unfamiliar ones — on the reasoning that closure was producing the non-compliance it existed to prevent, since a list you must consult and amend before tagging is a list sessions skip.

The Excalidraw wrinkle dissolved rather than being fixed: .excalidraw.md files carrying plugin frontmatter are no longer violations, and assets are exempt outright because they aren't pages.

What this extends beyond the gist. Karpathy treats index.md as a file the LLM writes and frontmatter as optional plugin sugar. But description and sources are precisely the two things wiki/index.md maintains by hand — so putting them in frontmatter makes the catalog derivable rather than transcribed, and turns index drift from a lint category into an impossibility. That inverts the relationship between the two: the index becomes a projection of the pages, not a parallel record of them.

Related

• agent-memory-at-scale — tests this pattern's central scaling assumption (that an index file suffices to ~hundreds of pages) and locates where it breaks.
• claude-code-memory-architecture — the other file-and-index system in play, with hard mechanical limits this pattern has no equivalent of.
• okf-spec — a spec formalising the same markdown-plus-links shape for machine interop; explicitly cites this gist as its grounding.
• ai-agent-architecture — §7 context engineering; the wiki is a supply format.

References

• Source: llm-wiki-karpathy — Andrej Karpathy, LLM Wiki, Apr 2026. https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
• The gist's comment thread (dozens of community implementations, and discussion of team-scale concerns like PR gates and page locks) was not captured — only the document body. Worth a second pass if team use ever becomes relevant.
• qmd: https://github.com/tobi/qmd