# The LLM Wiki Pattern: A Second Brain That Compounds

> RAG (retrieval-augmented generation) rediscovers knowledge every time. My wiki accumulates it instead. This is Andrej Karpathy's LLM Wiki Pattern, built with a Claude agent that maintains the whole wiki.

Every AI coding session starts the same way. The model has no memory of the last session. You explain the project again, paste the same documents again, and find the same answers you found last week.

RAG helps: it retrieves relevant chunks and feeds them as context. But this is still rediscovery. The model reads the raw sources fresh every time. Nothing builds up. Nothing connects.

I wanted a different approach. Andrej Karpathy described one: the [LLM Wiki Pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). So I built it.

https://x.com/karpathy/status/2039805659525644595

## The LLM Wiki Pattern

Karpathy's idea is simple. Instead of retrieving from raw sources at query time, an LLM agent builds a linked wiki step by step. Sources go in once. The wiki grows over time. Each session starts where the last one ended.

```text
raw/sources/          ← immutable source documents
wiki/
├── entities/         ← people, orgs, projects, concrete things
├── concepts/         ← ideas, patterns, theories
├── sources/          ← one summary page per raw source
├── synthesis/        ← cross-source analysis
├── index.md          ← full catalog
├── log.md            ← append-only activity timeline
└── hotcache.md       ← recent context, read first
```

Raw sources are never changed. The agent owns and maintains the wiki. When a new source comes in, the agent reads it, writes a summary page, updates the related entity and concept pages, links everything together, and adds an entry to the log.

## The Hotcache

The most useful piece is `hotcache.md`, a summary of about 500 words that covers the current wiki state. The agent reads this file first in every session.

```text
Who pyyupsk is. Active projects. Key concepts. Recent activity. Naming conventions.
```

The agent can answer most questions from the hotcache alone. When it cannot, it reads `index.md` and then opens specific pages. The agent loads the full context only for deep queries.

This is what makes the system fast. Loading a large wiki in every conversation is expensive. The hotcache reduces that cost to one file, most of the time.

## What the Agent Does

Six commands run the system:

| Command                       | What it does                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `/wiki-llms:ingest <path>`    | Read source → summarize → update entity/concept/index/log/hotcache             |
| `/wiki-llms:query <question>` | Answer via hotcache → index → drill in, then file valuable synthesis back      |
| `/wiki-llms:lint`             | Health check: contradictions, stale claims, orphans, broken links, index drift |
| `/wiki-llms:status`           | Counts + last 5 log entries + active threads                                   |
| `/wiki-llms:hotcache`         | Refresh hotcache from current wiki state                                       |
| `/wiki-llms:page <slug>`      | Open a wiki page by slug (fuzzy match)                                         |

Ingest is the core loop. You drop a source file into `raw/sources/` with a `YYYY-MM-DD-kebab-case.md` name. You run `/wiki-llms:ingest`. The agent then handles everything after that.

All six commands are available as Claude Code slash commands in [this gist](https://gist.github.com/pyyupsk/19ada0b5b5bb9fdf586ad04c8e16c4e2).

## Why It Is Better Than RAG

RAG is stateless, meaning it keeps no memory between queries. Every query starts again at the raw sources. The model builds understanding from scratch each time. This works, but it does not accumulate. You get answers, not knowledge.

A wiki accumulates:

- Cross-references: The agent built these during ingest, not during your query.
- Contradictions: Lint runs catch these before they confuse you.
- Synthesis: Synthesis pages hold cross-source analysis that no single document contains.

When I ask about a specific architectural pattern, the agent does not read six source documents again. It reads the concept page, which already combines them.

## The Lint Pass

The most useful habit I built was running `/wiki-llms:lint` after every batch of ingests.

The last pass on 2026-04-22 caught:

- 52 broken wikilinks. The agent created 30 stub pages and fixed the rest as typos.
- 34 Biome source files mapped to 3 umbrella summary pages. The agent documented this structural drift.
- Index drift: the agent added 31 missing rows.

Without lint, the wiki rots the same way most documentation rots. It rots quietly and invisibly, until it becomes wrong enough to mislead you.

## What Is Stored

The scope stays specific: knowledge management architecture, my developer tooling ecosystem, and AI agent workflows. It does not cover everything. It covers only the areas I work in constantly and need lasting context for.

Entities cover tools, frameworks, people, and projects. Concepts cover patterns, ideas, and design decisions. Synthesis covers cross-source analysis that I otherwise lose between sessions.

## The Real Payoff

The difference shows up when you return to a project after two weeks away.

Without the wiki, you read the README again, search the codebase again, and ask questions you have already answered. With the wiki, you read the hotcache, read the entity page, and start working.

Context loading used to be a hidden cost in every conversation. The wiki solves that problem.

## What I Would Change

The naming convention is strict: every source file needs a `YYYY-MM-DD-kebab-case.md` name. When a file does not match, the agent asks before it ingests the file. This is the right choice, but it adds friction when I process files in batches.

Synthesis pages need more attention. The most valuable insights live in synthesis, but this is the step I am most likely to skip when I move fast.

## Retrieval vs. Memory

RAG is retrieval. A wiki is memory. Retrieval finds what you have stored. Memory is what you have understood.

This is the first time my AI context has felt truly persistent. It is not just cached. It accumulates. Each session starts a little further ahead than the last.

You drop sources in. The agent builds the understanding. You ask questions. You can come back tomorrow, and the context is still there.