mirror of https://github.com/Ar9av/obsidian-wiki.git synced 2026-09-14 20:36:34 +08:00

Files

T

Arnav 52c9f2bae2 feat(server): run a vault as a Dockerized HTTP + MCP memory service (#185 )

Everything else here is local: skills on your machine, a vault on your disk.
This puts a vault behind a URL so an agent elsewhere can search and write it.

One container, one vault, one API key. The vault stays plain markdown on a
mounted volume, so Obsidian still opens it. The container does no LLM work --
search and packing delegate to the existing graphrag/context_pack modules, and
the caller's agent does the thinking.

- obsidian_wiki/server.py: four vault functions, five REST routes and four MCP
  tools as transport over them. Auth is one bearer key; the process refuses to
  start without WIKI_API_KEY unless WIKI_ALLOW_ANONYMOUS=1. Every path is
  resolved inside the vault or refused.
- Dockerfile, docker-compose.yml, .dockerignore, and a ghcr push on v* tags.
- New [server] extra; the core wheel stays dependency-free.
- docs/deployment.md, plus the WIKI_* vars in configuration.md and .env.example.

Requires mcp>=2.0: 2.0 renamed FastMCP to MCPServer, and session_manager only
exists once streamable_http_app() has been called -- a mounted sub-app's own
lifespan is ignored, so it is wired into the FastAPI lifespan by hand.

2026-08-21 14:37:37 -07:00

9.8 KiB

Raw Permalink Blame History

obsidian-wiki

一個由 AI agent 陪你一起養大的數位大腦。

它會記住你弄懂的事，把新知識連到你已經知道的內容，
並在你提問時回答。

English | 繁體中文

你在某個星期二解掉一個難題。三個月後，在另一個 repo 裡，你又從頭解了一次，因為答案躺在一份你永遠找不到的對話紀錄裡。

這個專案解決那個問題。指定一個資料夾，告訴你的 agent 要記住什麼，它就會把你學到的東西編譯成彼此連結、而且屬於你自己的 markdown。這個模式來自 Andrej Karpathy 的 LLM Wiki gist：把知識編譯一次並持續維護，而不是每次都問 LLM 同樣的問題，或每次都重新跑 RAG。

你的第二大腦；AI agent 是你讓它成長的方式。

這裡每個 skill 都是一個 markdown 檔案，任何 agent 都能讀取並執行，包括 Claude Code、Cursor、Codex、Windsurf、Gemini CLI，以及另外十幾種。沒有 runtime、沒有 API key、不綁任何廠商。

60 秒上手

pip install obsidian-wiki
obsidian-wiki setup --vault ~/brain

然後在你的 agent 裡打開任何專案，說 「set up my wiki」。

不想碰終端機？把下面這行交給你的 agent，它會全部處理好：

https://github.com/Ar9av/obsidian-wiki — set up my wiki

其他安裝方式（git clone、Skills CLI、多個 vault）請見 安裝說明（英文）

你實際會做的事

餵養它。 任何文字形式的東西：文件、PDF、聊天匯出、會議逐字稿、截圖、網址。

/wiki-ingest ~/research
/wiki-update                        # 蒸餾你目前所在的這個 repo（支持使用 codegraph 增強程式碼結構解析）
/wiki-capture                       # 把這段對話存下來
/wiki-history-ingest claude         # 挖出你問過 Claude 的所有東西

問它。 回答會附上 [[wikilink]] 引用，而不是憑感覺。

/wiki-query what do I know about rate limiting?
/wiki-narrate MCP security          # 針對一個主題產生有引用的簡報
/wiki-digest week                   # 我這週學到了什麼？

找出那個你叫不出名字的 session。

obsidian-wiki sessions-build
obsidian-wiki sessions-query "the auth bug with the weird retry loop"

維持它的品質。 vault 自己會變亂，這些 skill 負責整理。

/wiki-lint            # 壞掉的連結、孤兒頁面、互相矛盾的內容
/wiki-dedup           # 「RSC」和「React Server Components」現在是同一頁了
/cross-linker         # 把新頁面編織進知識圖譜
/wiki-status          # 已匯入什麼、還有什麼待處理、樞紐頁面在哪

全部 39 個 skill 請見 Skills Reference（英文）

看見它

在 Obsidian 打開 vault，然後開啟 graph view（Cmd/Ctrl+P → 「Open graph view」）。說 「color my graph」，它就會依照 tag、category 或 visibility 為節點上色。

你也可以把整個圖譜匯出成 graph.json、GraphML（Gephi/yEd）、Neo4j Cypher、Postgres SQL，或一個自帶所有資源的互動式 graph.html。

為什麼不是一個筆記資料夾就好

它會編譯，而不是堆積。 新知識會合併進既有頁面，矛盾會被標記出來，內容不會重複。
它只讀有變動的部分。 manifest 追蹤每個匯入過的來源，所以第二次執行只處理差異，而不是重跑整個資料庫。
你分得出哪些是知識、哪些是猜測。 每個陳述都會標記為 extracted、^[inferred] 或 ^[ambiguous]，lint 會標出開始偏向臆測的頁面。
查詢成本不隨規模爆炸。 先讀標題、tag 和 summary，需要時才打開頁面內容。20 頁或 2000 頁，成本差不多。
它是你的。 就是資料夾裡的純 markdown。推到私人 repo、用 Obsidian 打開、用 grep 搜、直接刪掉都行。沒有服務、沒有鎖定，什麼都不會離開你的機器。
在你原本工作的地方就能用。 一個 .skills/ 目錄，symlink 到你使用的每一個 agent。

更多細節請見 Architecture（英文）

真的有幫助嗎？

結構性問題——「X 和 Y 是怎麼連起來的」、「哪些頁面撐住了整個 vault」、「刪掉這頁會壞掉什麼」——正是一般 agent 最不擅長的。它每一次都得 grep 過所有檔案，再自己把連結圖重建一遍。

同一個模型、同一個 vault、同樣的問題，唯一的差別是有沒有裝 obsidian-wiki：

	一般 agent	裝了 obsidian-wiki
回答耗時	81 秒	19 秒 — 快 4.4 倍
答對比例	44%	83%
使用的工具呼叫次數	9.9	4.6
API 成本	$0.202	$0.208 — 沒有變化

問題	一般 agent	裝了 obsidian-wiki
「X 和 Y 是怎麼連起來的？」	122 秒	18 秒
「我有哪些主題叢集？」	117 秒	21 秒
「哪些頁面撐住了整個 vault？」	61 秒	12 秒
「刪掉 X 會壞掉什麼？」	26 秒	24 秒

正確率的差距不是誤差。被要求追出一條連結路徑時，一般 agent 會繞過 index.md——那頁連到每一個頁面，所以它「找到」了一條毫無意義的短路徑。兩次執行都犯了同樣的錯，而且還把 index 說成 vault 裡最重要的頁面之一。這些 skill 查詢的圖已經排除了記帳用的檔案，所以那種答案根本不會出現。

方法，以及這個測試無法證明的事

使用 Claude Sonnet，以 headless 模式在一個真實的 38 頁 vault 上執行。問題都用一般口語提出，沒有另外說明圖的定義——一般 agent 有 Read/Grep/Glob/Bash，得自己想辦法（它做得不錯，甚至自己寫了一份中心性演算法，而不是隨便猜）。4 個問題 × 2 種條件 × 2 次重複，序列執行，避免互搶 CPU。

基準答案來自 networkx，而不是本專案自己的程式碼：betweenness 在每個節點上的誤差都在 3.5e-18 以內，630 組最短路徑也全部一致。

這是個小規模測試——每格 n=2，只用了一個 38 頁的 vault——所以確切的百分比僅供參考。時間差距（3～6 倍）遠大於各次執行之間的波動；正確率的數字則建立在較少的樣本上。「裝了」那一欄有一次執行完全失敗：模型沒有使用 CLI，自己 grep，然後答錯了。

完整資料、每次執行的紀錄與規模測試結果都在 PR #175。

文件

以下文件目前為英文版本。


Installation	pip、clone、由 agent 設定、多個 vault
Skills Reference	全部 39 個 skill 與其 slash command
Agent Compatibility	完整相容性表格與各 agent 手動設定
CLI Reference	每一個 `obsidian-wiki` 子命令
Configuration	設定變數、QMD 語意搜尋、`_raw/` 暫存區、GitHub 同步
Architecture	四個匯入階段、vault 結構、我們在 Karpathy 模式上加了什麼
Session Brain	建立在 agent session 歷史之上的主題圖譜
Browser Extension	將網頁擷取進 vault，並用 vault 內容填寫網頁表單
Deployment	以 Docker 將 vault 部署成記憶服務，讓 agent 透過 HTTP/MCP 存取
Contributing	新增 skill、維持兩份 README 同步

參與貢獻

這個專案還很早期。skills 是能用的，但還有很多空間讓這個大腦變得更聰明：更好的交叉引用、更精準的去重、支撐更大的 vault、更多匯入來源。如果你有一個工作流程適合做成 skill，歡迎送 PR。

授權

MIT

9.8 KiB Raw Permalink Blame History Unescape Escape