把公共智慧 pull 回家，
長成自己的知識庫

# 個人 BIM 知識庫（LLM Wiki）— 給 AI Agent 的建置說明

這是一份「想法檔」：請你（AI Agent）讀完後與我協作，在我的電腦上把這個
個人知識庫實際建出來。細節由我們一起決定，這份文件只負責溝通模式。
模式源自 Andrej Karpathy 的 LLM Wiki 概念，並針對 Revit MCP 專案特化。

## 核心概念

一般 RAG 每次提問都從原始文件重新檢索拼湊，知識不會累積。這裡不同：
你要替我「增量維護一個持久的 wiki」—— 一組互相連結的 markdown 筆記。
每次有新來源進來，你不是只索引它，而是閱讀、萃取、整合進既有 wiki：
更新相關頁、標記矛盾、修正既有綜述。知識編譯一次、持續保鮮。

wiki 由你寫和維護，我幾乎不動手。我負責：提供來源、引導方向、問好問題。
你負責：摘要、交叉引用、歸檔、簿記。實際使用時我會一邊開著你（agent）、
一邊開著 Obsidian 看圖譜和頁面。Obsidian 是 IDE，你是工程師，wiki 是程式碼庫。

## 三層架構

vault 直接住在我的 REVIT_MCP clone 裡面（https://github.com/shuotao/REVIT_MCP_study）。
repo 本身就是 raw 層；個人區是 repo 內的 vault/ 資料夾，上游 .gitignore
已排除 /vault/ 與 /.obsidian/，所以個人筆記永遠不會被 push 上去。

1. raw 層 = repo 根目錄的所有上游內容。我只透過 git pull 更新；
   你只讀、永不修改。重點來源：
   - domain/*.md：72 個 Domain SOP（各領域老師貢獻的公共智慧，
     frontmatter 含 version、updated、related、referenced_by、references、tags）
   - domain/references/building-code-tw.md：建築技術規則彙整
   - .claude/skills/*/SKILL.md：50 個編排層 Skill
   - CLAUDE.md：公共 wiki 的 schema（Domain 觸發關鍵字表在這裡；
     它的開發規則只適用於開發本專案，vault 操作以 vault/CLAUDE.md 為準）
   - log/YYYY-MM.md：公共 wiki 的時間軸
2. vault/wiki/ —— 我的個人知識層。完全由你建立與維護：概念頁、實體頁、
   比較頁、綜述頁。允許 Obsidian 的 [[雙向連結]]，連到 domain 檔
   會在 graph view 形成公共＋個人合一的知識族譜。用我的語言、我的分類、
   我的重點 —— 這是「個人壓縮」，不必跟上游長一樣。
3. vault/CLAUDE.md（schema）—— 你的紀律設定檔。
   ※ 重要：這個檔不由你生成，而是從
   templates/personal-vault/VAULT-CLAUDE.md 逐字複製過來
   （Fixed Core 區塊一個字都不能改寫、濃縮或重新表述；
   只有最後的 Personal 區由我們一起填）。
   這是讓每位使用者、每種 AI Agent、每個模型等級建出來的 vault
   規則一致的機制：一致性靠複製，不靠模型自律。

兩個特殊檔（都在 vault/ 內）：
- vault/index.md：wiki 目錄。每頁一行連結＋一句摘要，每次 ingest 後更新。
- vault/log.md：append-only 時間軸，條目格式沿用上游慣例：
  ## [YYYY-MM-DD HH:MM] 事件類型 | 簡述

## 三個操作

1. Ingest：我說「ingest」時 —— 先在 repo 根目錄執行 git pull，
   再用 git diff 找出上次 ingest 之後變動的檔案，只消化變動部分：
   閱讀、跟我討論重點、寫入或更新 vault/wiki/ 頁、更新 vault/index.md、
   追加 vault/log.md。
2. Query：我問問題時 —— 先讀 vault/index.md 找相關頁再深入。
   重要：好的答案要存回 wiki 成為新頁（分析、比較、發現的關聯
   都不該消失在對話裡）。特別的是，repo 的 .mcp.json 已設定 Revit MCP：
   你可以直接對「活的 Revit 模型」提問（執行排煙檢討、查詢元素、
   跑法規檢核）。把實際審查的結果也 file 回 wiki，讓案例經驗複利累積。
3. Lint：我說「lint」時 —— 檢查：
   (a) 哪些 wiki 頁的來源已在上游更新（比對 source_version 與上游現況）
   (b) 頁面之間的矛盾
   (c) 沒有任何連入連結的孤兒頁
   (d) 值得回饋上游的發現，整理成「可提案清單」
   (e) vault/CLAUDE.md Fixed Core 的 schema_version 是否落後
       templates/personal-vault/VAULT-CLAUDE.md —— 落後就提示升級
       （新版 Fixed Core 整段覆蓋，Personal 區保留）

補充：若你是 Claude Code，本 repo 已內建 /ingest、/lint、/wiki 三個
斜線指令，內容就是轉接到以上定義；其他 CLI（Codex / Gemini）以
自然語言觸發，新 session 第一句建議先說「讀 vault/CLAUDE.md」。

## 紀律（必須遵守）

1. 個人操作永不寫入 vault/ 以外的任何檔案；個人筆記永不 commit 到
   上游 repo；個人 log 一律寫 vault/log.md（不是上游的 log/）。
2. 永不在本 repo 執行 git clean -x 系列指令（會刪掉整個 vault/）、
   永不 git add -f vault 內容。vault/ 要自己 git init 並建議推私人遠端備份。
3. 溯源：每個源自上游的 wiki 頁，frontmatter 必須記 source
   （如 domain/smoke-exhaust-review.md）與 source_version
   （抄該檔 frontmatter 的 version 與 updated）。
4. 答案中的具體數據（元素 ID、數量、面積）必須來自本回合的工具結果，
   不可憑記憶 —— 與上游 CLAUDE.md 的「資料誠實」原則一致。
5. 法規與計算方法以 domain/*.md 為準；我的 wiki 是個人理解層，
   與 Domain 衝突時，在 lint 報告中標記，不要擅自改寫結論。

## 回饋上游（這個 vault 的終極目的之一）

當 lint 或日常使用發現：兩個 SOP 應該相關但上游 related 欄是空的、
某 SOP 缺法源依據、某流程有更好的做法、或我發展出值得共享的新應用 ——
協助我整理成提案，透過上游的 /hj-pr-proposal skill 或每月小聚提出 PR。
個人深化的成果回到公共智慧，循環才算完成。

## 建置步驟（現在開始）

0. 前提確認：我們現在應該位於 REVIT_MCP clone 的根目錄
   （用 git remote -v 確認；若我還沒有 clone，先協助我 clone）。
   再確認 .gitignore 含有 /vault/ 與 /.obsidian/（上游已內建；
   若沒有代表我的 clone 太舊，先 git pull）。
1. 建立 vault/ 與 vault/wiki/，以及空的 vault/index.md、vault/log.md。
2. 在 vault/ 內執行 git init（獨立的個人 repo，與上游互不干擾），
   並建議我之後推一個私人遠端做備份。
3. 把 templates/personal-vault/VAULT-CLAUDE.md 逐字複製為
   vault/CLAUDE.md（Fixed Core 不得改寫），然後問我幾個
   個人化問題填入 Personal 區：我的專業領域？我最常用哪些 Domain？
   我偏好的筆記語言與粒度？
4. 執行驗收清單，逐項回報給我：
   [ ] vault/、vault/wiki/、vault/CLAUDE.md、vault/index.md、vault/log.md 都存在
   [ ] .gitignore 含 /vault/ 與 /.obsidian/，且 git status 看不到 vault/
   [ ] vault/CLAUDE.md 的 Fixed Core 與 templates/personal-vault/
       VAULT-CLAUDE.md 逐字一致（用 diff 確認），schema_version 相同
   [ ] vault/ 已 git init（有自己的 .git）
   [ ] 上游工作區乾淨（git status 無本地修改）
   [ ] vault/log.md 已寫入第一筆標準格式條目
   [ ] 之後每個源自上游的 wiki 頁都會帶 source 與 source_version
5. 做第一次 ingest：從我的專業最相關的兩三個 Domain 檔開始，
   不要一次吞 44 個。
6. 提醒我用 Obsidian 打開 REVIT_MCP 資料夾（不是 vault/）、
   在 Settings → Files and links → Excluded files 排除 MCP-Server/ 與 MCP/、
   然後看 graph view —— wiki 頁連到 domain 檔的邊會出現在圖上。

## 附錄：Andrej Karpathy「LLM Wiki」原文全文

以下用三引號包住的是這個模式的原始出處全文（英文）。請完整讀過它
作為概念錨點 —— 當你不確定某個設計該怎麼做時，回到原文的精神判斷，
不要憑記憶腦補。原文與本說明衝突時，以本說明的 REVIT_MCP 特化規則為準。

"""
# LLM Wiki

A pattern for building personal knowledge bases using LLMs.

This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.

## The core idea

Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.

The idea here is different. Instead of just retrieving from raw documents at query time, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then kept current, not re-derived on every query.

This is the key difference: the wiki is a persistent, compounding artifact. The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.

You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.

This can apply to a lot of different contexts. A few examples:

- Personal: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
- Research: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
- Reading a book: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like Tolkien Gateway — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
- Business/team: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
- Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives — anything where you're accumulating knowledge over time and want it organized rather than scattered.

## Architecture

There are three layers:

Raw sources — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.

The wiki — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.

The schema — a document (e.g. CLAUDE.md for Claude Code or AGENTS.md for Codex) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.

## Operations

Ingest. You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.

Query. You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: good answers can be filed back into the wiki as new pages. A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.

Lint. Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.

## Indexing and logging

Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:

index.md is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.

log.md is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. ## [2026-04-02] ingest | Article Title), the log becomes parseable with simple unix tools — grep "^## \[" log.md | tail -5 gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.

## Optional: CLI tools

At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. qmd is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.

## Tips and tricks

- Obsidian Web Clipper is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
- Download images locally. In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. raw/assets/). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
- Obsidian's graph view is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
- Marp is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
- Dataview is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.

## Why this works

The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.

The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.

The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.

## Note

This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.
"""