--- LLM: Claude type: blueprint slug: personal-wiki lang: en date: 2026-04-17 title: "Blueprint: Personal Wiki" tagline: An LLM builds a wiki from your notes — automatically description: An LLM compiles a coherent wiki from scattered notes. Synthesis, not summaries. Incremental, with cross-links and an auto-generated index. audience: For anyone who takes notes in Obsidian, Notion, or markdown and wants to turn them into a connected knowledge base --- # Blueprint: Personal Wiki Notes pile up for months — podcast summaries, article clips, research notes. Everything sits in your inbox and slowly drowns. You know there's value buried in those files, but extracting it means sitting down and re-reading everything. That never happens. This Blueprint solves the problem: an LLM reads your raw notes, clusters them by topic, and compiles a coherent wiki. Not a summary of each file, but synthesis — a unified narrative from multiple sources. The wiki grows with you: every new podcast or article automatically enriches existing articles. Inspired by Andrej Karpathy's approach ("LLM Knowledge Bases"). ## What You Get - **A wiki from your notes** — coherent articles compiled from scattered sources, with cross-references - **An automatic pipeline** — a skill or command to compile new notes into the wiki in a single run - **A living index** — a table of contents and changelog to see the full picture and track knowledge growth - **Incremental updates** — only new and modified notes are processed on subsequent runs ## How to Apply 1. Open a coding agent (Claude Code, Cursor, Codex) **in your vault directory** 2. Show it this Blueprint: "Build me a Personal Wiki using this Blueprint" 3. The agent will ask questions from the "Adaptation Questions" section 4. Answer about your folders, conventions, tools 5. The agent will create the wiki folder, index files, and a compilation skill **Context:** a single session with the vault as the working directory. The agent needs file access to read sources and create the wiki. ## When to Use - Notes accumulate in inbox/research/podcasts but never get synthesized - You need to see the full picture on a topic, not individual files - You want to ask complex questions against your knowledge base - AI summaries are useful but get lost in the flow — you need structure ## Core Idea **You don't write the wiki by hand. The LLM compiles it from raw material and maintains it.** Human: - Collects raw material (clips, summaries, research) - Chooses what to compile - Asks questions against the wiki - Decides which topics to go deeper on LLM: - Clusters raw material by topic - Compiles concept articles (synthesis, not summaries) - Adds cross-links - Maintains the index and changelog - Creates synthesis articles (second-order) - Runs linting (consistency, coherence, gaps) ## Architecture ``` Sources (raw) Wiki (compiled) ----------------- ----------------- Inbox/ --+ Research/ +---> LLM ---> Wiki/ Podcasts/ --+ | +-- _Index.md | +-- _Changelog.md | +-- Article A.md <-- primary | +-- Article B.md <-- primary | +-- ... | +-- Synthesis X.md <-- second-order | +-- Synthesis Y.md <-- second-order | +---> Tag sources: wiki-status: processed ``` ### Three Layers 1. **Raw** -- unedited notes. Never modified by the LLM (except adding status). Source of truth. 2. **Primary articles** -- compiled from raw. One article = one topic cluster drawn from multiple sources. 3. **Synthesis articles** -- compiled from primary articles. Cross-cutting concepts that only emerge when you look at the whole picture. ## Key Principles ### 1. Synthesis, Not Summaries A wiki article is a **unified narrative**, not a list of per-source recaps. The LLM reads all sources in a cluster, finds intersections, contradictions, and patterns, then writes a coherent text. Specific data, quotes, and numbers are preserved. But the structure is original, not copy-paste. ### 2. Statuses Track Progress Every raw file gets a `wiki-status` field in its metadata (YAML frontmatter, properties, or whatever your tool uses): | Status | Meaning | |--------|---------| | *(no field)* | Unprocessed | | `raw` | Explicitly marked as unprocessed | | `processed` | Compiled into the wiki | | `updated` | Edited after compilation -- needs recompilation | This enables incremental runs: on re-run, the LLM only processes new and changed files. ### 3. Flat Wiki Structure All articles live at one level, no nested folders. Why: - Easier to link (references do not break on reorganization) - The link graph is cleaner - No "where does this go" debates -- put it in wiki, connect with links ### 4. Index and Changelog Are Meta-Files **_Index.md** -- a table of all articles with topic, source count, and date. The LLM updates it on every compilation. Replaces RAG for small-to-medium bases -- the LLM reads the index and knows where to look. **_Changelog.md** -- a log: date, which articles were compiled, from which sources. Provenance -- you can always trace where things came from. ### 5. Cross-Linking Closes the Graph After compilation -- a mandatory pass across all articles: - **"See also"** -- a section at the end of each article linking to related articles - **Inline links** -- the first mention of a concept covered by another article becomes a link - Links must match file names exactly (a common source of broken references) ### 6. Synthesis Reveals Hidden Themes After the initial compilation pass, the LLM analyzes ALL articles and finds themes mentioned in 3+ articles but not fully covered anywhere. These are candidates for synthesis articles -- second-order compilation. They have no raw sources; their sources are other wiki articles. ## Workflow ### Initial Compilation (Cold Start) ``` 1. Scan all sources -> list of files with topics 2. Cluster by topic (2+ files = a cluster) 3. Show topic map to human -> human selects 4. Run cluster compilation (in parallel) 5. Tag sources with wiki-status: processed 6. Update _Index.md and _Changelog.md 7. Lint: add cross-links 8. Propose synthesis articles -> human selects 9. Compile synthesis ``` ### Single Ingest (one file -> wiki) When a single new piece of content appears (listened to a podcast, read an article): ``` 1. Human: "here is a podcast, summarize it" 2. LLM: creates summary -> saves to the appropriate source folder 3. LLM: reads _Index.md -> does it fit an existing article? +-- Yes -> enriches the article with new content, tags, writes to changelog +-- No -> leaves as raw (picked up during batch compilation) 4. If article was updated -> quick lint (new cross-links) ``` **Key principle:** don't hoard -- integrate immediately if there is somewhere to put it. As Karpathy puts it: *"I end up filing the outputs back into the wiki to enhance it for further queries. So my own explorations always add up."* **"Fits" criteria:** - The main topic matches an existing article - It adds new data, a contrasting viewpoint, or deeper analysis - It does not simply duplicate what is already covered ### Batch Compilation (many files -> wiki) When unprocessed notes have piled up: ``` 1. Find files WITHOUT wiki-status (new) 2. Find files with wiki-status: updated (changed) 3. Cluster only those 4. Show topic map -> human selects clusters 5. Compile in parallel -> new articles or additions 6. Re-lint the entire wiki (new articles may create new connections) 7. Propose synthesis articles if new cross-cutting themes appeared ``` ### Q&A (using the wiki) ``` 1. Human asks a question 2. LLM reads _Index.md -> finds relevant articles 3. Reads articles -> formulates an answer 4. (Optional) The answer is saved as a new note -> filed back into the wiki ``` ### When to Use What | Situation | Process | |-----------|---------| | Listened to a podcast, read an article | **Single ingest** -- summary + integration | | 5+ new notes have accumulated | **Batch** -- clustering + compilation | | Need an answer on a topic | **Q&A** -- question against the wiki | | Haven't updated wiki in a while | **Batch** + **lint** + **synthesis** | ## Components ### Clusterer For each file, the LLM determines: - Main topic (2-5 words) - Language (en/ru/etc.) - Content type (research, summary, meeting notes, pitch, raw dump) Grouping: files with overlapping topics -> one cluster. Files without a match -> "unclustered" -> catch-all article or wait for the next batch. ### Compiler (one per cluster) Input: - List of files to read - Output article name - Recommended structure (sections) - Tags Output: - One wiki article (markdown) - Updated metadata in source files Article requirements: - Synthesis, not retelling - Specific data (numbers, quotes, names) - Links to sources - 1500-3000 words (large cluster), 800-1500 (small) ### Linter Passes over all wiki articles and: - Adds "See also" sections with contextual explanations - Inserts inline links on first mention of a concept - Finds inconsistencies (the same number stated differently) - Finds redundancies (duplicated text between articles) - Proposes synthesis article topics (mentioned in 3+ articles, no dedicated article) ### Synthesizer Same as the compiler, but: - Input is wiki articles, not raw files - Goal is to extract a cross-cutting theme and write a coherent narrative - Adds **emergent insights** -- conclusions visible only at the intersection of topics - Uses `synthesis-of` instead of `sources` in metadata ## Article Metadata ### Primary article ```yaml type: wiki-article created: YYYY-MM-DD sources: - "[[Source File 1]]" - "[[Source File 2]]" tags: [wiki, topic-tags] ``` ### Synthesis article ```yaml type: wiki-article created: YYYY-MM-DD synthesis-of: - "[[Wiki Article A]]" - "[[Wiki Article B]]" tags: [wiki, topic-tags, synthesis] ``` ## Adaptation Questions Before building, the agent asks you these questions to tailor the architecture to your specific setup. ### Sources - Which folders hold your raw notes (inbox, research, podcast summaries)? - Are there other sources worth including (meeting notes, clips, bookmarks)? - What languages are your notes in? ### Wiki structure - What should the wiki folder be called? Any preferences on where it sits in the vault? - Flat structure (all articles in one folder) or subfolders by topic? - How should article files be named -- English, your native language, mixed? ### Metadata - Do you use YAML frontmatter in your notes? Any mandatory fields? - Is there a tagging system in the vault that needs to be respected? ### Workflow - How does new content typically arrive -- one file at a time or in batches? - Do you want scheduled automation (cron/scheduled agent) or manual on-demand runs? - Who decides on clusters -- you every time, or can the agent decide autonomously? ### Tools - Which coding agent are you using (Claude Code, Cursor, Codex, other)? - Does it support running parallel agents? - Does it have file system access to the vault? ## Gotchas and Pitfalls ### Links must match file names The most common bug -- the LLM generates a link like `[[File Name and Extra Words]]`, but the file is actually called `File Name.md`. Obsidian (and other tools) cannot resolve the reference. Verify links after every compilation. ### Files belonging to multiple clusters A single note can be relevant to two topics. Rule: **one cluster tags, others reference**. Otherwise you get conflicts during parallel compilation. ### Parallel compilation Clusters are independent -> compile in parallel (each in its own agent). This matters at 5+ clusters -- sequential compilation takes 5x longer. The only constraint is shared files (see above). ### Index replaces RAG (up to a point) Karpathy notes: at ~100 articles and ~400K words, the LLM manages without RAG as long as the index files are well-maintained. The LLM reads _Index.md, finds the right articles, reads them. Beyond 200+ articles, you may need a search layer. ### Do not mix compilation with manual notes The wiki is LLM territory. If you want to add your own thoughts, add them as a raw note in the source folders and trigger recompilation. Or use a dedicated section in the article (## My Notes) that the LLM does not overwrite. ### A catch-all article is inevitable There will always be files that do not fit any cluster. Better to collect them in a single "Miscellaneous" article than to leave them unprocessed. As the knowledge base grows, they may become the seed of a new cluster. ### wiki-status: updated must be tracked manually The LLM does not know a file changed after processing (no file watcher). Two options: - You set `updated` manually when editing a processed source - A script compares mtime with the compilation date in the changelog ## Scaling The pattern works for: - **Research** -- papers, articles, Twitter threads -> research wiki - **Podcasts** -- summaries -> topical knowledge base - **Course/book** -- scattered drafts -> structured outline - **Competitive intelligence** -- competitor monitoring -> living wiki - **Onboarding** -- docs, processes, FAQ -> knowledge base for new hires - **Personal OS** -- all notes -> searchable, linked second brain ## Reference Implementation Obsidian + an AI agent (Claude Code, Cursor, Windsurf, or any other agent with file system access). | Component | Implementation | | ------------- | ------------------------------------------------------------------------------------------------- | | Sources | 2-3 folders with raw notes (inbox, research, podcasts -- or however you organize) | | Wiki | A dedicated folder (e.g. `Wiki/`), flat structure with no subfolders | | Index | `Wiki/_Index.md` -- table of all articles with topic, source count, and date | | Changelog | `Wiki/_Changelog.md` -- compilation log: date -> article -> from which sources | | Statuses | YAML frontmatter `wiki-status: processed` in every processed source file | | Clustering | AI scans sources -> builds topic map -> human selects clusters | | Compilation | One agent per cluster (parallel, if the tool supports it) | | Linting | Separate pass over all articles: cross-links, "See also", link verification | | Synthesis | Separate pass: topics mentioned in 3+ articles -> synthesis article candidates | | Automation | Script or command for re-running (skill, slash command, Makefile -- depends on the tool) | **Typical cold start output:** from ~50-100 raw notes you get 8-15 primary articles and 3-5 synthesis articles. ## Output Artifacts After setup, you should have: | Artifact | Description | How to verify | |----------|-------------|---------------| | Wiki folder | A dedicated folder with flat structure | Exists, empty or with first articles | | `_Index.md` | Table of all articles | File exists, table format is correct | | `_Changelog.md` | Compilation log | File exists, has at least one entry | | Source statuses | `wiki-status: processed` in processed files | Grep across sources confirms | | Primary articles | Compiled articles from clusters | Have source links, "See also" section | | Cross-links | Inline links and "See also" between articles | Links are not broken, point to existing files | | Skill or command | A way to re-run compilation | Running the command processes new files | **Not required on cold start, but will appear over time:** - Synthesis articles (after 5+ primary articles accumulate) - Catch-all article for unclustered notes - Scheduled automation (if chosen)