What is the CLAUDE.md wiki pattern?

Instead of stuffing every fact into one CLAUDE.md file, you keep CLAUDE.md small and use it as a front door: it tells the assistant to read a wiki index at the start of every session, then load only the few pages relevant to the task. The config file bootstraps the memory; the wiki holds it.

Why not just put everything in CLAUDE.md?

A flat CLAUDE.md grows until it's too large to load every session and too tangled to maintain. Splitting durable knowledge into a linked wiki keeps the always-loaded file lean, lets the model pull only what it needs per task, and makes each fact editable on its own. CLAUDE.md becomes the router, not the warehouse.

Does this only work with Claude?

The file is named for Claude and Claude Code, but the pattern is model-agnostic. Any assistant that can read files at the start of a session can use the same wiki. The bootstrap file is the only Claude-specific piece, and it's a few lines.

The CLAUDE.md wiki pattern: turn one config file into a memory system

Q: How do I keep the wiki from going stale?

With enforcement, not discipline. A hook flags changed files for re-documentation, a scheduled pass hunts stale pages and dead links and reports to a channel you actually read, and a rule says work isn't done until the docs reflect it. The system assumes the notes will rot and fights it mechanically.

Turn one config file into a memory system: keep CLAUDE.md small and use it as a front door to a markdown wiki your AI reads at the start of every session.

The problem with a flat CLAUDE.md

The first instinct is to pour everything into CLAUDE.md: every preference, every project fact, every rule. It works for a week. Then the file grows until it's too large to load every session and too tangled to maintain. Now the model carries dead weight and still misses the one thing it needed for today's task.

The pattern: router, not warehouse

The fix is to split the job in two. CLAUDE.md stays lean and becomes the router: a short file the assistant reads first that tells it to load a wiki index, then pull only the few pages relevant to the work at hand. The warehouse is the wiki: a folder of markdown, one durable fact per page, linked from an index that acts as the front door.

CLAUDE.md (always loaded, small)
↓ bootstraps
wiki/index.md (the front door, what exists, what to read when)
↓ loads only what's relevant
topic pages · regressions · running log

What goes where

In CLAUDE.md: the bootstrap instruction ("read the index first"), a handful of non-negotiable rules, and pointers. Nothing that changes weekly.
In the wiki: project state, how your infrastructure fits together, conventions, a regressions file of corrected mistakes, and a running log of what changed and why.
The index: the one page that tells the model what to read for a given kind of task, so it loads a few pages, not the whole pile.

Keeping it honest: enforcement

A wiki that depends on you remembering to update it will rot. So the pattern leans on enforcement, not discipline: a hook flags changed files for re-documentation, a scheduled pass hunts stale pages and dead links and reports to a channel you actually read, and a rule says work isn't "done" until the docs reflect it. A warning written to a log nobody reads is the same as no check at all.

Why it's worth the setup

Because the file is named for Claude, but the payoff is model-agnostic. When a new model or tool ships, you point it at the same wiki and it resumes with your context instead of a blank chat. This is the CLAUDE.md-flavored version of the Karpathy memory system: durable, owned, file-based memory, with the config file as its front door.

Frequently asked

Why not just put everything in CLAUDE.md?: It grows until it's too big to load every session and too tangled to maintain. A linked wiki keeps the always-loaded file lean and lets the model pull only what it needs. CLAUDE.md becomes the router, not the warehouse.
Does this only work with Claude?: No. The bootstrap file is the only Claude-specific piece, and it's a few lines. Any assistant that reads files at session start can use the same wiki.
How big should CLAUDE.md be?: Small enough that loading it every session costs nothing you'd notice. If it's growing, that's the signal to move a section into the wiki and leave a pointer.

The CLAUDE.md wiki pattern