The Knowledge Base That Builds Itself

In The Context Wall, I described what happens when your AI knowledge base outgrows a single file — and how QMD solves the retrieval problem by searching your markdown files instead of loading them wholesale into the context window.

That article solved one half of the equation. There’s another half.

Retrieval and knowledge maintenance are different jobs. A search engine helps find existing evidence; an agent can help draft and update derived summaries. Both need checks against the underlying sources.

Maintaining a knowledge base manually can become a bottleneck. Meeting insights, architecture decisions and discovered edge cases need to be recorded, filed and linked to related knowledge. An agent can help with that bookkeeping while the source and review requirements remain explicit.

Andrej Karpathy’s LLM Wiki proposal describes an agent-maintained collection of summaries and linked knowledge pages. The pattern is useful to evaluate on its technical merits without relying on a popularity count or an expanded biography.

Pattern source: Andrej Karpathy’s LLM Wiki gist. The implementation and reliability guidance here should be evaluated for the intended workspace.

The proposed division of work is straightforward: people select authorized sources and review important interpretations; an agent can draft summaries, suggest links and identify inconsistencies. Those operations still need validation.

This article is the complete guide: what the LLM Wiki pattern is, how it works technically, how to implement it with Claude Code, when to use it, when not to, and how it combines with QMD for the full knowledge management stack.

Two Problems, Not One

When your AI knowledge base stops working, it’s tempting to treat it as a single problem. But there are actually two distinct problems hiding under the surface:

The reading problem: Your knowledge base is too large for the context window. Your AI can’t see everything you’ve documented. Information gets missed.

The writing problem: Your knowledge base is too tedious to maintain. You stop updating it. Knowledge that should be documented never gets written down. Cross-references go stale. The file becomes a mess.

QMD solves the reading problem. The LLM Wiki solves the writing problem. They’re complementary — different tools for different pain points. Understanding which problem you’re actually facing determines which tool you need.

The LLM Wiki Pattern

Karpathy’s key insight: most people use LLMs as search engines over their documents. Upload files, retrieve chunks, get an answer. The LLM rediscovers knowledge from scratch on every question. Nothing compounds.

A wiki can preserve a reviewed synthesis so that later questions need less repeated interpretation. It must also preserve provenance and a way to recheck the original when precision, changes or disagreement matter.

The durable artifact is the wiki and its source relationships, rather than one conversation’s answer.

An editor can make those files convenient to inspect; an agent can propose changes under the wiki’s maintenance rules.

An Idea, Not an App

Here’s the fascinating part: Karpathy didn’t publish code. No library. No CLI tool. No npm package. He published a markdown document — an "idea file" describing the pattern. That’s it.

A written pattern can help someone design an implementation for a particular workflow. It is still a design input, not an executed, tested system.

Use the proposal to identify the desired behavior and acceptance criteria. Then verify the resulting implementation, including how it handles incorrect or conflicting sources.

A clear natural-language specification can guide implementation. Code, configuration and checks are still necessary wherever the workflow requires them.

Implementations differ in storage, permissions, retrieval and review. Assess those requirements before selecting or building a tool.

• Storage: preserve originals and identify derived files.
• Provenance: link each important derived claim to its supporting source.
• Review: expose the proposed change and handle disagreement.
• Operations: retain failure evidence, version history and a recovery path.

A small pilot can use Markdown files and a coding agent. It still needs an agreed structure, appropriate permissions and a way to review edits. Add specialized tools when their operational benefit is demonstrated.

The idea is a starting point for implementation. The gap between a proposal and a reliable system remains work that must be checked.

The Three-Layer Architecture

The pattern organizes knowledge into three distinct layers, each with clear ownership:

Layer 1: Raw Sources

What: The original documents — articles, papers, meeting transcripts, Slack exports, design docs, images. Stored in a raw/ directory.

Who owns it: You. These are immutable. The LLM reads them but never modifies them. This is the source of truth you can always verify against.

Why it matters: When the LLM makes a mistake in the wiki (and it will), you can always trace back to the original source. This layer is your insurance policy against hallucination compounding.

Layer 2: The Wiki

What: LLM-generated markdown files — summaries, entity pages, concept pages, comparisons, synthesis. Stored in a wiki/ directory.

The agent proposes or applies changes within its authorized scope. People remain responsible for the wiki’s purpose, important interpretations and correction process.

Why it matters: This is the compiled knowledge. Instead of reading a 20-page research paper every time you need a fact from it, you read the LLM’s distilled summary with cross-references to related concepts. The compilation is done once. Every future query benefits from it.

Layer 3: The Schema

What: A configuration document (your CLAUDE.md) that tells the LLM how the wiki is structured — naming conventions, page formats, workflows, tag taxonomy.

Who owns it: You and the LLM together. You set the initial structure; the LLM suggests improvements as the wiki evolves.

A schema makes expected structure explicit. It does not guarantee compliance; validate required fields and links, and review semantic changes against the sources.

The Directory Structure

project/
  CLAUDE.md              # Schema — wiki conventions, workflows, formats
  raw/                   # Immutable source documents
    articles/
    papers/
    meeting-notes/
    assets/              # Images, PDFs
  wiki/                  # LLM-generated, LLM-maintained
    index.md             # Master catalog of all pages
    log.md               # Chronological activity record
    entities/            # People, organizations, projects
    concepts/            # Ideas, frameworks, theories
    sources/             # Per-source summaries
    synthesis/           # Cross-source analysis pages

The Three Operations

Everything the LLM does with the wiki falls into three operations:

Ingest

You drop a source into raw/ and tell the LLM to process it. Here’s what happens:

1. The LLM reads the source document
2. Discusses key takeaways with you (optional but recommended)
3. Writes a summary page in wiki/sources/
4. Updates the master index.md
5. Updates or creates relevant entity pages (people, organizations mentioned)
6. Updates or creates relevant concept pages (ideas, frameworks discussed)
7. Adds cross-references between new and existing pages
8. Appends an entry to log.md

One source can affect several pages. Keep the initial pilot small enough to inspect every proposed change and confirm that the cross-references preserve the source’s meaning.

Query

Ask questions against the wiki. The LLM reads index.md first (the master catalog), finds relevant pages, reads them, and synthesizes an answer.

The powerful insight: good answers get filed back into the wiki as new pages. If your query produces a valuable synthesis — a comparison between two frameworks, a decision analysis, a gap identification — that becomes a permanent wiki page. Your explorations compound into reusable knowledge.

Lint

Periodic health checks. Tell the LLM to audit the wiki for:

• Contradictions — two pages claiming different things about the same topic
• Stale claims — information that may have changed since it was compiled
• Orphan pages — pages with no inbound links from other pages
• Missing concepts — topics referenced frequently but without their own page
• Gaps — areas where a web search could fill in missing knowledge

Use linting to surface candidates for review. Some checks, such as broken links, can be deterministic; contradiction and freshness judgments may require reopening the source. A completed model pass does not prove the wiki is consistent.

The Two Special Files

index.md — The Master Catalog

This is the most important file in the wiki. It’s a content-oriented catalog of every page, organized by category, with one-line summaries. The LLM reads this first when answering any query — it’s the table of contents that lets it navigate the entire knowledge base.

A concise index can be sufficient for some collections. Its usefulness depends on the content, questions and navigation behavior, not a universal source-count limit.

When the wiki outgrows what index.md can handle, that’s where QMD comes in. More on that later.

log.md — The Activity Record

A chronological, append-only record of everything that happens in the wiki: ingests, queries, lint passes. Each entry uses a consistent format:

## [2026-04-09] ingest | "Payment Reconciliation Architecture"
Source: raw/articles/payment-recon.md
Pages created: concepts/settlement-processing.md, entities/stripe.md
Pages updated: index.md, concepts/payment-flows.md
Cross-references added: 7

## [2026-04-09] query | "How do settlement timelines differ by provider?"
Pages consulted: concepts/settlement-processing.md, entities/stripe.md, entities/adyen.md
Result filed as: synthesis/settlement-timeline-comparison.md

The log is an audit aid. Its completeness depends on whether all relevant changes are captured; compare it with version history and source records when that assurance matters.

Implementing With Claude Code

Here’s how to set this up in practice with Claude Code.

Step 1: Create the Directory Structure

mkdir -p raw/articles raw/papers raw/meeting-notes raw/assets
mkdir -p wiki/entities wiki/concepts wiki/sources wiki/synthesis
touch wiki/index.md wiki/log.md

Step 2: Configure CLAUDE.md

Add the wiki schema to your CLAUDE.md. This is the key configuration that turns Claude from a generic assistant into a disciplined wiki maintainer:

## LLM Wiki

This project maintains a knowledge wiki in `wiki/`.
Raw sources live in `raw/` (immutable — never modify).

### Page Format
Every wiki page uses this structure:
- YAML frontmatter: title, created, updated, tags, sources
- **TLDR** section: 2–3 sentence summary
- Main content with H2/H3 sections
- **Related** section: links to related wiki pages
- **Sources** section: links back to raw/ documents

### Ingest Workflow
When asked to ingest a source:
1. Read the source in raw/
2. Create a summary page in wiki/sources/
3. Create or update relevant entity pages in wiki/entities/
4. Create or update relevant concept pages in wiki/concepts/
5. Add cross-references between new and existing pages
6. Update wiki/index.md with new entries
7. Append to wiki/log.md

### Query Workflow
When asked a question:
1. Read wiki/index.md to find relevant pages
2. Read those pages
3. Synthesize an answer
4. If the answer is valuable, file it as a new page in wiki/synthesis/

### Lint Workflow
When asked to lint:
- Check for contradictions between pages
- Flag stale claims
- Identify orphan pages with no inbound links
- Suggest missing concepts that should have their own page

### Naming Conventions
- Files: lowercase, kebab-case (e.g., payment-reconciliation.md)
- Tags: lowercase (e.g., architecture, payments, compliance)
- Keep coherent concepts together. Split at meaningful boundaries when navigation or review benefits.

Step 3: Ingest Your First Source

Drop a document into raw/ and tell Claude:

Ingest raw/articles/payment-reconciliation-architecture.md

Claude reads it, creates summary and entity pages, updates the index, and logs the activity. Watch it work the first few times — this is where you calibrate quality and adjust the schema if needed.

Step 4: Query the Wiki

How do settlement timelines differ between Stripe and Adyen?

Claude reads the index, navigates to the relevant pages, synthesizes an answer with citations back to wiki pages and original sources. If the answer is valuable, ask Claude to file it as a new synthesis page.

Step 5: Periodic Maintenance

Lint the wiki

Claude audits the entire wiki structure, reports contradictions, flags stale content, identifies orphan pages, and suggests improvements. Do this weekly — or whenever the wiki has grown significantly since the last lint.

The Full Stack: QMD + LLM Wiki Together

This is where it gets powerful. QMD and the LLM Wiki solve different problems, and they combine naturally.

For a collection whose index remains useful, direct navigation may be sufficient. Test representative questions and inspect which sources the agent actually consulted.

Add search when navigation or context costs become a measured problem. The number of sources alone does not determine whether an index fits or whether the model will use it correctly.

QMD + LLM Wiki: QMD indexes the entire wiki directory. Instead of reading index.md to find relevant pages, Claude calls qmd query to search across all wiki pages semantically. The LLM still writes and maintains the wiki; QMD handles retrieval at scale.

project/
  CLAUDE.md              # Schema + QMD instructions
  raw/                   # Immutable sources (you add these)
  wiki/                  # LLM-maintained (Claude writes these)
    index.md             # Small/medium wikis: Claude reads this
    ...                  # Large wikis: QMD searches instead

The progression:

1. Start with clear source ownership and a simple navigation method.
2. Add retrieval when representative tasks reveal a discovery problem.
3. Add agent-assisted maintenance when it improves curation without losing provenance or review.

You don’t need to jump to step 3 from day one. Each step addresses a specific pain point. Adopt them as you feel the pain, not before. KISS still applies.

When Each Approach Makes Sense

Stay With a Single ctx.md When:

• The available context and navigation support representative tasks.
• The material is manageable under the existing review process.
• A simpler structure meets the required access and maintenance boundaries.

Add QMD When:

• Known sources are hard to discover through the current navigation.
• Measured context or latency costs justify selective retrieval.
• You can operate and validate the retrieval index.

Add LLM Wiki When:

• You’re receiving knowledge from many sources (meetings, docs, Slack, research)
• You find yourself not documenting things because the maintenance is too tedious
• Cross-references between knowledge areas are getting stale or missing
• You want knowledge to compound — each new source enriching the whole base
• The writing is the bottleneck — too tedious to maintain manually

Use Both When:

• Both source discovery and maintenance create recurring friction.
• Representative tests show value from combining the two.
• The workflow preserves provenance, permissions and a correction path.

Honest Limitations

The LLM Wiki pattern is powerful. It’s also imperfect. Here are the real tradeoffs:

Hallucination Compounding

The most serious risk. If the LLM makes a subtle error when compiling a source — a slight misinterpretation, a wrong attribution — that error becomes a permanent fact in the wiki. Future queries reference it. Future ingests build on it. The error compounds.

Mitigation: the raw sources layer is your safeguard. You can always verify wiki claims against originals. Periodic lint passes can cross-check. But this requires discipline — trust but verify.

Knowledge Drift

Over time, the wiki may gradually diverge from source truth through accumulated small edits. Each individually reasonable, together they shift the meaning. This is especially risky when switching between LLM models or across long time periods.

Mitigation: every wiki page links back to its source documents. The log.md tracks every change. Git history provides full version control. The audit trail is built in.

The "Brain Gap" Problem

This is the philosophical objection, and it’s worth taking seriously. If the LLM does all the synthesis, do you actually learn? The Zettelkasten tradition argues that the act of writing is the act of thinking — that friction is cognition. Remove the friction, and you might remove the understanding.

Generated notes can create a gap between possessing a summary and understanding the source. That is a reason to inspect and challenge the synthesis, not to infer that every user experiences the same effect.

The pragmatic response: use the wiki as input to your thinking, not a replacement for it. Read what the LLM compiles. Challenge it. Ask follow-up questions. The wiki is a starting point for understanding, not the destination. Let the machine build the map — then walk the territory yourself.

Cost at Scale

Maintenance consumes model and tool resources, especially when one source affects several pages. Measure actual work and review effort rather than assuming a fixed number of pages per ingest.

Not For Everything

The pattern works best for stable, research-oriented knowledge — architecture decisions, domain concepts, synthesis of multiple sources. It works less well for highly dynamic contexts where information changes daily, like project management status or sprint planning. For that, simpler approaches win.

A modern associative knowledge system

Linked notes and associative trails predate current language models. The relevant continuity is the value of connecting a document to the evidence and ideas that make it useful.

An agent-maintained wiki is one contemporary way to support that work. It complements a long history of hypertext, wikis and other knowledge-management tools.

Maintenance remains necessary: sources change, links break and interpretations can conflict. Automation can help surface this work without eliminating the responsibility to assess it.

Models can omit a cross-reference or propagate an error. Preserve the original sources and evaluate maintenance behavior rather than claiming the system never forgets.

The practical objective is a reviewable, evolving technical record—not a claim that one pattern is the first working realization of a historical vision.

The Full Picture

Zoom out and you can see the complete knowledge management evolution for AI-native engineering:

1. Single file — You write it, Claude reads it. Simple, transparent, manual. (The Knowledge Equation)
2. QMD — You write it, QMD searches it. Scales reading, still manual writing. (The Context Wall)
3. LLM Wiki — Claude writes it, Claude reads it. Scales both. You curate sources and ask questions. (This article.)
4. LLM Wiki + QMD — Claude writes it, QMD searches it. The full stack. Scales everything.

Choose each component for an observed need. A small pilot with explicit acceptance criteria is a better basis for expansion than a fixed progression everyone is expected to follow.

As I wrote in The Knowledge Equation, domain knowledge is the real differentiator in AI-native engineering. The tools to capture, maintain, and retrieve that knowledge are maturing rapidly. What hasn’t changed — and won’t change — is that the knowledge itself has to come from somewhere. From your experience. Your domain expertise. Your years in the trenches.

The infrastructure is getting better. The hard part stays the same.