There comes a moment in every team's life when an uncomfortable truth is accepted: the documentation is broken. The corporate wiki nobody maintains loses usefulness month after month. The RAG pipeline that connects LLMs to "everything we know" answers each query from scratch, without accumulating anything. Andrej Karpathy published a short gist proposing a third way: an LLM Wiki — a markdown knowledge base maintained by AI agents that compounds value over time.
The pattern is elegant and, in essence, correct. But when you take it from personal use to team use, new decisions emerge that the gist does not resolve. This article does two things: it acknowledges its strengths and describes the four nuances you will need to think through if you want to implement it with more than one person writing — humans, agents, or both.
Why Karpathy's proposal is correct
Karpathy precisely articulates the core problem of how LLMs interact with documents today. In a classic retrieval-augmented generation (RAG) pipeline, the model retrieves relevant chunks for each query and generates an answer. It works. But knowledge is not built: each answer rediscovers the synthesis from scratch. Five questions on the same topic produce five duplicated chains of reasoning.
And the traditional alternative — the human wiki — fails from exhaustion. Reading and thinking are not the tedious part. What is tedious is the bookkeeping: updating cross-references, keeping summaries current, flagging contradictions, maintaining consistency across 40 pages. Humans abandon wikis because the cost of maintenance grows faster than the value they receive in return.
Karpathy's proposal takes the human out of the loop: the wiki is a persistent artifact, but the bookkeeping is done by the LLM. The human curates sources, explores, asks. The LLM summarizes, links, archives, flags. A new paper enters the stock of raw sources and the agent touches 10 or 15 wiki pages in a single pass. The wiki stays maintained because the cost of maintenance approaches zero.
The architecture it proposes has three layers: immutable raw sources, a markdown wiki generated by the LLM, and a schema file (CLAUDE.md, AGENTS.md or similar) that tells the agent how everything is organized. Elegant, minimalist, fundamentally correct.
Principle: Useful knowledge is not re-derived on every query. It is compiled once and kept up to date.
First nuance: where the sources live
Karpathy places the raw sources inside the same repo as the wiki, in separate subfolders (for example raw/ and wiki/). For personal use with Obsidian it works well: everything is in one directory, the Web Clipper pastes articles there, and the line between "what you read" and "what you concluded" is clear.
On a team the model breaks down. The sources a team consumes are heterogeneous and live on different platforms: papers in Zotero, threads in Slack, recordings in Fireflies or Otter, emails in Gmail, PDFs in Drive. Forcing a local replica of all of that into a repo is duplication with no benefit and, worse, it pretends to give immutability to something another platform manages.
The right way out is to accept that the wiki layer and the sources layer are different systems. The wiki stores synthesis; the sources live where they are born. The critical piece is citation: when an agent writes something synthesized from external material, it must leave a trace of what it consulted. Otherwise the claim becomes folklore — nobody can verify where it came from or whether it is still valid.
The recommended pattern is dual. On one hand, a ## Sources section at the end of the doc — human-readable, versionable in git, rendered by any markdown renderer. On the other, a structured metadata field (YAML frontmatter, a JSONB column in a DB, or the equivalent in your stack) with the same machine-parseable list. Two representations of the same truth, because they serve two different consumers.
If that sounds like duplicated work, think of it this way: structured metadata is what later lets you detect that a source was updated, and therefore that the docs citing it should be reviewed. That use justifies the cost.
Principle: Source immutability comes from not touching them, not from copying them. Citing is enough.
Second nuance: the explicit graph that LLMs do not need
In a markdown wiki there are two overlapping graphs. One is the explicit one: the links [text](./other.md) that a human sees when opening the file. The other is the semantic one: the proximity between docs that embeddings capture.
Agents do not need the explicit one. They navigate by similarity — "give me the 5 most relevant chunks for this query" is a vector index, not link following. Humans do need it: when someone opens the repo on GitHub or Obsidian, explicit links are what turn isolated documents into a navigable network.
When the LLM is the one writing the wiki, that explicit graph degrades silently. The agent adds a new doc and forgets to link it from related docs. It adds a link from A to B but forgets the backlink from B to A. Six months later you have 80 docs, of which only 20 are well connected, and nobody noticed because the agent kept answering questions without problems via embeddings.
The solution is to treat the explicit graph as a separate product and audit it actively. Three useful signals to compute:
- Orphans: docs with no incoming or outgoing links. No human finds them by browsing.
- One-way: docs with only incoming or only outgoing links. A sign that a backlink is missing.
- Semantically close pairs without a link: docs with high vector similarity but no markdown link between them. Real candidates for the cross-linking the agent did not see.
All three are cheap queries if you materialize the graph in a separate table (source, destination, anchor, heading of the section where the link lives). The cost of maintaining it is marginal compared to re-indexing embeddings, and its value for the team's humans is high.
Principle: The explicit graph is not a byproduct of the semantic graph. It is a different view, with a different consumer, and it deserves its own health discipline.
Third nuance: two agents writing at the same time
In Karpathy's personal setup there is a single agent touching the wiki, usually with direct human supervision in the same window. Write conflicts are impossible: there is only one writer.
On a team, the model breaks immediately. One agent is summarizing a meeting while another ingests a paper; both touch the doc arquitectura.md in different sections. Without coordination, the last commit wins. Five minutes of analysis are silently overwritten. Nobody detects the loss until days later, when a third person notices "this used to say something else".
The recommended pattern is old and solid: optimistic locking by content hash. Before writing a section, the agent reads the current version and receives a hash. When writing, it passes that hash as expected_version. If the current version on the server does not match — because another agent wrote in between — the system responds with version_mismatch along with the current version and lets the agent reconcile instead of overwriting.
It is the same pattern distributed systems have used for decades:
- In CouchDB and Cloudant, each document carries a
_revthat you must send when updating. - In DynamoDB, you use a
ConditionExpressionon a version attribute. - In PostgreSQL,
UPDATE ... WHERE version = :expectedand you check the rowcount. - In Redis,
WATCH+MULTI/EXECaborts the transaction if the key has changed. - In HTTP REST,
ETag+If-Match. - In git,
git pushrejects a non-fast-forward push.
The form changes, not the idea. And it is the difference between a "one-person wiki" and a "multi-person wiki". Many open source LLM-wiki projects do not implement it — it works well for the author alone and breaks when a team adopts it.
Principle: Collaboration between agents demands the same concurrency disciplines as between humans. Perhaps more, because agents write faster.
Fourth nuance: linting is not one operation, it is several
Karpathy describes linting as a periodic pass: "ask the LLM to look for contradictions between pages, obsolete claims, orphan docs, concepts without a dedicated page, missing cross-references, data gaps that could be filled with web search". In one paragraph it is simple. In practice, each has a different cost, cadence and trigger.
| Check type | Cost | Natural cadence |
|---|---|---|
| Orphans, one-way, similar-without-link | Cheap SQL query | On demand at each audit |
| Docs with no cited sources | Metadata check | On demand |
| Recurring concepts without a dedicated page | Heuristic over headings | On demand or at ingest |
| Obsolete claims (stale claims) | Comparison with updated sources | When a source changes |
| Contradictions between docs | LLM-heavy, O(N²) candidates | Background with controls |
Putting all of this under a single "lint" tool invoked manually is a simplification that does not survive growth. It is better to separate it into buckets that are computed independently, with different cadences: the cheap ones on every query, the expensive ones in the background.
For the most expensive case (contradictions), the risk is that the cost explodes with the size of the wiki. Without controls, comparing every pair of chunks gives O(N²) calls to an LLM. With 1,000 docs and five chunks each, that is 12 million pairs. Unsustainable.
Three controls that keep the cost linear:
- Top-K neighbors per chunk instead of "all pairs with high similarity". Each chunk checks only its 3 nearest neighbors. The cost grows linearly with the number of chunks, not quadratically.
- Delta mode: only re-check pairs involving chunks edited since the last run. In steady state the cost scales with the editing rate, not with the total size.
- Budget cap per tenant: a monthly ceiling on calls. If it is reached, it pauses and prioritizes re-verifying existing high-severity findings. It guarantees predictable costs.
With these three controls, a 10,000-doc wiki that nobody edits costs almost the same as a 50-doc, very active one. The combinatorial explosion disappears. And if you have well-done source tracking (first nuance), "stale claims" is practically solved for free using the retrieval dates.
Principle: Expensive features are designed with limits from day one. Optimizing late costs more than limiting early.
Checklist before implementing the pattern in your team
If you decide to go with Karpathy's pattern adapted to teams, these are the axes to think about from the start:
- Where do the sources live and how does the agent cite them when writing? Do you have a dual representation, human-readable and structured?
- How do you detect and report orphan docs, one-way docs, and semantically close pairs without a link? Is the explicit graph materialized in a table you can query?
- What concurrency mechanism do you use when two agents — or an agent and a human — can edit the same doc? Are you on optimistic locking or on "last one wins"?
- Did you separate linting into buckets with different costs and cadences? Do you have budget caps for the LLM-heavy features?
None of these is a major architectural decision. All are small details that, if omitted, make the wiki ungovernable within 3 to 6 months of growth.
A note from the trenches
We arrived at these nuances as a team that works with AI agents daily and needed a shared knowledge base between people and agents. The traditional local wiki — an Obsidian on each person's machine, half-synced via Drive — quickly became too small for us. We could not guarantee that everyone saw the same version, nor audit who had written what without asking for permission, nor prevent two parallel agents from stepping on each other while summarizing different parts of a long meeting.
We built Blenau to solve exactly the four nuances described here, in a product any team in the same situation can adopt: a shared wiki layer where the team's git remains the source of truth, with automated auditing along the four axes, optimistic locking between agents, and built-in source tracking from the start. If you prefer to implement your own version of the pattern, Karpathy's original gist remains an excellent starting point — and the four nuances in this article are the pieces you will end up adding anyway.
Shared knowledge infrastructure has always been a human problem. What changed is who does the bookkeeping, and everything that this forces you to rethink.