How an LLM Wiki Works
How an LLM wiki works, shown on this knowledge base: Markdown in its own Git repository, a Python tool with MCP for agents, and a website that only displays it.
Reviewed by adrian
on
An LLM wiki, following Andrej Karpathy's pattern, is a knowledge base that an LLM agent maintains together with its owner. This article shows how one works, using this knowledge base as the example. Instead of a list of posts it is a knowledge graph: every point is a Markdown file, every line a relation written in that file.1
Principle
The Markdown files are the project. Everything else, from the tooling to the rendering, can be replaced without touching a single note. Why there is a graph next to the lists is explained in Why a Graph, the reasons for files instead of a database in Markdown as a Database.
Data, tool and website
The knowledge base started inside the website project and was moved out of it, so that it no longer depends on a website build. There are three parts:
- The knowledge base is a folder of Markdown and YAML files in its own Git repository on my Mac. It holds only data.
- The
kbtool is a small local Python program with a command line and an MCP server. It validates, searches, exports and writes the knowledge base, and it is the only part that writes. - The website only displays the knowledge base: it reads the nodes, the notes, the ontology and the log while it runs, loads them again within seconds when a file changes, and never writes to them.4
The search index and the embedding model live in a cache folder outside the knowledge base, so iCloud and Git do not sync the model files.3 With BGE-M3 they take about 600 MB.5
The three layers
- Raw sources:
raw/holds the source material. New material lands inraw/inbox/; an agent files it by topic into a folder for the day,raw/<year>/<date>/, as one Markdown file per topic, or a folder when images come with it. Filed sources are read only for agents, except for chat summaries the MCP tool saves into the day folder. - The wiki: the nodes in the type folders of
en/andde/, written by the agent and reviewed by me. - The rules:
AGENTS.mddescribes the workflows: ingest a source, add a chat, answer a question, lint the graph. The ontology inontology.yamland the schema belong to the rules as well.
Next to the wiki, en/notes/ and de/notes/ hold my notes: short dated entries with an optional photo. They are not nodes, have no relations and stay out of the graph, the search and the OKF bundle. A note that links a node is listed on that node's page.
Content model
- One file per node in
<language>/<folder>/<id>.md, for exampleen/topics/markdown.md. The file name is the ID and the URL/n/<id>/; the folder only keeps things tidy. - A strict frontmatter schema: title, type, a summary of 40 to 180 characters, dates, tags, typed relations, an optional link,
draft,private, and provenance fields. - The ontology in
ontology.yamldefines the entity types (topic, tool, project, article, source, place) and the relation types (about, builds-on, part-of, uses, source, related; mentions is derived from links in the text), with their rules and their German names. - The graph has a fixed structure. The index leads to the main topics, topics divide into subtopics (
part-of), articles and projects areabouttopics, and tools and sources come in through the articles and projects that use or cite them. Topics link neither tools nor sources. Each entity type names the types it may connect to (connects), andkb lintreports links and relations that break this.4 kb checkvalidates every file against the schema and the ontology: allowed subject and object types, at least oneaboutper article, no relation declared in both directions, no cycles in transitive relations, footnotes that match source IDs, andraw/files that exist. Every write through MCP runs the same check first.3- Tags are lowercase words joined by hyphens, in the language of the content. A tag gets no edge in the graph; a node with the same ID as a tag explains it on the tag page.
- Drafts and private nodes never reach the public site. A published node cannot point to a draft, and a public node cannot point to a private one.
Graph view
All relations together form a graph, shown on its own page, /knowledge-graph/. The home page introduces the site and lists the latest notes and changes. The server computes the layout with a Python port of ForceAtlas2, followed by a step that separates the nodes. An index node is pinned in the center and links the main topics, the topics without a parent topic. The browser draws the graph with Sigma.js and Graphology.
The view was redesigned after I pointed to another LLM wiki site as an example:
- small nodes whose size grows with their number of connections, labels to the right, thin edges, arrows only on the edges of the focused node;
- an intro animation: nodes start near the center and settle into the computed layout with damped springs (skipped when the system asks for reduced motion);
- a glow instead of a frame on hover and a ring on the selected node, while unrelated nodes fade;
- a reading panel that loads the full node page, including provenance and sources, and follows links inside the graph; it slides in from the right, and a button shows or hides it;4
- a legend below the graph to show or hide entity types, and a graph that fills nearly the whole viewport.
Pages and exports
Every entity type is a section of the site (/topics/, /tools/, /projects/, /articles/, …) with a reading page per node. Every node also has its page at /n/<id>/ with its relations in both directions, provenance ("Written by", "Reviewed by", flags for unreviewed or stale content) and sources. There are the notes at /notes/, all tags at /tags/ with one page per tag that lists nodes and notes together, and an ontology page. The website also serves, generated on request:4
graph.jsonwith the nodes, edges and layout;- a RAG export:
/rag/chunks.jsonl(text sections with metadata and provenance),/rag/triples.jsonl(one line per edge) and/rag/ontology.json; - an Open Knowledge Format (OKF 0.2) bundle under
/okf/: one Markdown file per node, listings per type, the ontology and the log. It covers the English content.
kb export writes the same files in the same format without a website.3
Two languages
The site exists in English and German. German pages live under /de/ with the same paths, and a switch in the header leads to the same page in the other language. Every interface text of the website is defined once per language; the German names of the entity and relation types come from ontology.yaml.3
Content is separate per language: every language has a folder of its own in the knowledge base (en/, de/), and each language is a graph of its own, so German nodes only relate to and link German nodes. A German file with the same name as an English one is its translation; the language switch and the hreflang links connect the two. The log is English and exists only on the English site.
Search
kb index embeds the published and private nodes of both languages locally with the multilingual model BGE-M3 (Xenova/bge-m3), so German questions also find English content, without an API key. Drafts stay out, and only changed sections are embedded again. German nodes have the key de/<id> in the index. A query combines vector search with a minimum score of 0.48, graph expansion along the edges of the hits, and the definitions of the relation types involved. This is retrieval-augmented generation over a graph. Sections written by an agent and not reviewed by a person are marked with a caution. kb query --prompt prints the retrieved context as a prompt for any LLM.3
Until November 2026 the model was multilingual-e5-small. I measured it against four other local models with 26 test questions: BGE-M3 put the right node first for all 26, e5-small for 19. The old minimum score of 0.75 had filtered nothing, since even unrelated questions reached 0.81 with e5-small.5
Agents
A Model Context Protocol server, knowledge-base, gives agents access to the knowledge base. It is part of the kb tool and runs over stdio; Claude Desktop and Claude Code both start it with kb mcp. Its tools take the entity and relation types from ontology.yaml. A running server reads the files fresh; when the code of the tool or the set of types changes, it asks to be reconnected instead of working with an outdated state.4
- Read:
search_knowledge,get_node,get_neighbors,list_nodes,get_ontology. They cover both languages and take an optionallangto stay in one. - Write:
add_to_knowledge_basesaves a chat summary inraw/<year>/<date>/and creates nodes as drafts or extends existing ones. Adefield adds the German version of a node, with the same file name; its relations are kept only where the other node exists in German. Each call is one transaction: change the files, validate the whole knowledge base, restore every file on an error, then add a log entry, update the search index and commit exactly the touched files with my git identity. Files with uncommitted changes are left alone.3 - Review:
list_draftsshows what waits for review in both languages;mark_reviewedrecords my review and publishes drafts. An ID covers both language versions of a node,en/<id>orde/<id>only one. Agents may only call it when I say I reviewed the nodes.
Operating model
log.mdrecords every ingest, review, lint and setup change, newest first, in the OKF log format.kb lintreports orphans, separate islands, unlinked mentions, thin nodes, similar tags, tags without a node of their own, drafts, unreviewed or stale nodes and raw sources not ingested yet, for each language separately. It also compares translations with their originals: a translation older than the original's last change, a relation the original has and the translation lacks, or a different type.3- Provenance follows OKF:
generatednames the agent,verifiedonly ever me,sourceswith footnotes back each claim,stale_aftermarks content that ages. - Files are written in English. Commits carry only my git identity.1
From toolbar to commands
The first version of the website showed three buttons in its dev server, Add source, Ingest and Lint, modeled on the LLM wiki site made with Caspian. They did not write nodes: they saved sources in raw/ and handed over a command for Claude Code.2
The buttons were removed when the website became a pure display, since it must not write to the knowledge base. Commands of the kb tool do their work now: kb raw add saves a source, kb raw list shows which sources are not ingested yet, and kb lint runs the health check.3
Log page
/log/ shows log.md on the site: one section per day, the operation of each entry as a label, and the node IDs in the entries linked to their pages.2
Stack
The kb tool is written in Python 3.14 with pydantic for the schema, ruamel.yaml for writing frontmatter without losing comments, the MCP Python SDK, and ONNX Runtime with the Hugging Face tokenizers for local embeddings. A test suite with pytest covers its rules.3 The website runs on FastAPI with Jinja templates, HTMX and Alpine.js, without a build step: no npm, no bundler, no TypeScript, and the JavaScript libraries, Sigma.js and Graphology among them, are self-hosted.4 The first version was a static website built with Astro 7 and TypeScript; it remains as a prototype.1
Open points
- A Git remote for the knowledge base, such as a bare repository; it has none yet.3
- A hosted MCP server so the knowledge base can also be filled from claude.ai on the web and on mobile. It needs hosting and authentication; the hosting is not decided yet.
- Before the first deployment of the website: set the real domain, and set up the push to the server, where a hook checks the knowledge base out for the website.4
-
Work sessions in Claude Code, summarized in the saved chat. ↩
-
Owner toolbar and log page, inspired by the Caspian LLM wiki (saved chat). ↩
-
Moving the knowledge base out of the website project (raw/2026/2026-11-14/moving-the-knowledge-base-out-of-the-website-project.md). ↩
-
The website on FastAPI and a fixed graph structure (saved chat). ↩
-
Measuring embedding models for the knowledge base search (raw/2026/2026-11-16/measuring-embedding-models-for-the-knowledge-base-search.md). ↩
Based on
-
Building the knowledge graph site with Claude Code
(
raw/2026/2026-11-11/building-the-knowledge-graph-site-with-claude-code.md) [chat-2026-11-11] -
Owner toolbar and log page, inspired by the Caspian LLM wiki
(
raw/2026/2026-11-11/owner-toolbar-and-log-page-inspired-by-the-caspian-llm-wiki.md) [chat-2026-11-11-2] -
Moving the knowledge base out of the website project
(
raw/2026/2026-11-14/moving-the-knowledge-base-out-of-the-website-project.md) [chat-2026-11-14] -
The website on FastAPI and a fixed graph structure
(
raw/2026/2026-11-14/the-website-on-fastapi-and-a-fixed-graph-structure.md) [chat-2026-11-14-2] -
Measuring embedding models for the knowledge base search
(
raw/2026/2026-11-16/measuring-embedding-models-for-the-knowledge-base-search.md) [chat-2026-11-16]
Topic
- LLM Wiki Andrej Karpathy's pattern for personal knowledge: an LLM agent reads each source once and works it into a growing set of interlinked notes.
Builds on
- Graphology JavaScript library for graphs as a data structure: nodes, edges, attributes and algorithms such as layouts or shortest paths.
- Knowledge Graph Knowledge as a network of nodes and named relationships rather than a chronological list. The structure shows what connects to what.
- Markdown Simple markup language for text. Files stay readable without special software and can be converted to HTML.
- Model Context Protocol Open protocol through which AI apps such as Claude Code and Claude Desktop connect to servers that offer them tools and data.
- Open Knowledge Format Vendor-neutral format from Google Cloud for knowledge that people and agents share: a directory of Markdown files with YAML frontmatter.
- Python General-purpose programming language with highly readable syntax. The standard for data analysis, automation and quick prototypes.
- Retrieval-Augmented Generation Answering questions with an LLM by first retrieving relevant passages from a knowledge store and giving them to the model as context.
- Sigma.js JavaScript library that draws graphs in the browser with WebGL and stays smooth even with thousands of nodes.
Mentioned
- Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.
- Static Website A website made of finished HTML files that are built once and then served unchanged. No server code, no database.
See also
- LLM Wiki Idea File Andrej Karpathy's idea file from April 2026: an LLM agent builds and maintains a wiki of linked Markdown files from raw sources.
- Markdown as a Database For a personal website, a folder of Markdown files with a structured header replaces the database, as long as a schema checks it.
- Measuring the Search of My Knowledge Base Five local embedding models against 26 test questions: why the search now runs on BGE-M3 instead of multilingual-e5-small, with a new minimum score.
- Securing a Hosted MCP Server Plan for a hosted MCP server for the knowledge base that claude.ai on the web and on mobile can use, while nobody else can.
- Why a Graph A list sorted by date shows what is new. A graph shows what belongs together. This website needs both.