LLM Wiki Pattern

This page covers how WitWiki concretely implements the LLM Wiki pattern, which is Andrej Karpathy's LLM Wiki idea file put into production. For the conceptual background — what the pattern is, why it beats query-time RAG, and where it comes from — see llm-wiki-pattern.

How WitWiki implements the three layers

The pattern's three layers map directly onto WitWiki primitives:

  • Raw sources → uploaded files (raw_sources), stored as KMS-encrypted blobs (per-org OrgEncryptionKey). Agents read sources via source_upload/wiki_getSource and mark them done with wiki_markSourceIngested so they aren't re-processed.
  • The wiki → markdown pages owned entirely by the agent. Every write goes through wiki_updatePage, which parses [[wikilinks]] and refreshes that page's edges in the link graph automatically.
  • The schema → each project's own CLAUDE.md/AGENTS.md conventions, plus the navigation files index (catalogue) and log (chronological audit trail), surfaced through wiki_getIndex/wiki_updateIndex and wiki_getLog/wiki_appendLog.

Everything is project-scoped and multi-tenant: a project belongs to an org, and an agent's API key bakes in the project it can touch. Projects within an org can be moved between orgs via cross-org project transfer (a project_transfers state machine).

The operations, as shipped

  • Ingest — wiki_listSources → wiki_getSource → wiki_listPages/wiki_getPage → wiki_updatePage (one source may touch many pages) → wiki_appendLog → wiki_markSourceIngested.
  • Query — hybrid retrieval combining PostgreSQL full-text search (tsvector, migration 0018) with pgvector embedding similarity (migration 0017). Agents search via wiki_listPages then read with wiki_getPage, and can file good answers back as new pages.
  • Lint — wiki_lint health-checks the whole wiki for orphan pages and dead wikilinks, with a per-project cooldown. After a large restructure, wiki_rebuildGraph re-parses every page and atomically rebuilds the link graph under a PostgreSQL advisory lock so concurrent rebuilds across instances serialize safely.

Write-time mechanics

WitWiki treats writes as first-class, governable events:

  • Versioning — every page write is tracked (migration 0019), so history is recoverable.
  • Write provenance — each write stamps last_agent (the writing identity, e.g. the API key label) and an estimated token count, surfacing each page's relative context cost.
  • Audit trail — org-level CRUD is recorded in an append-only, hash-chained audit log (migration 0012) for tamper evidence, separate from the human-readable wiki log.

Because an LLM commits its interpretation at write time, errors can compound and persist. External research on the agent-memory landscape (2024–2026) identifies write-time governance — contradiction checks against core facts before a write commits, plus a human-review queue for agent writes — as the clearest unmet gap in the category. WitWiki deliberately does not ship it. A naive gate adds latency and gets switched off, and the hard part is contradiction detection against facts already on the page, which is a retrieval and entailment problem rather than a sprint. What ships instead is everything that makes a bad write cheap to catch and undo: a name on every edit, a refusal when a write is based on a version that has since changed, and one-click restore. See llm-wiki-pattern for the category analysis.

Interfaces

  • MCP — the wiki, source, and project domains are exposed over the Model Context Protocol via Streamable HTTP at /mcp (https://api.witwiki.app/mcp). See mcp-tools for the full reference of the registered tools and resources (21 tools as of September 2026).
  • REST + Web — the same operations back the REST API and the Next.js web app, plus the witwiki CLI used for day-to-day operations in this repo.

Why it works

What wears a knowledge base down is the upkeep: cross-references, stale summaries, contradictions left unrecorded. People stop when that costs more than the pages return; an agent does not, and will revise many pages in one pass. WitWiki's job is to give that agent a durable, governed, multi-tenant place to do it. The deeper rationale lives in llm-wiki-pattern.