Your markdown vault, compiled into a 6-persona MCP team for Claude Code, Codex, OpenCode, and Gemini CLI. Headless-first. Cites, doesn't guess.
Language: English (this page) · 简体中文 — Guide: English · 简体中文 — Wiki: Home · Architecture · Rationale · FAQ
You have 500 markdown notes. You forget half of them. Your AI agent cannot read them -- it paraphrases from its context window and fabricates citations. Every morning you spend 20 minutes re-finding what you already knew.
LLM Wiki Bridge is a headless-first MCP server that compiles your vault -- wikilinks, aliases, tags, frontmatter -- into a concept graph your agent calls directly. The agent doesn't guess. It calls vault.search, reads the cited notes with vault.read, answers with evidence. Obsidian is optional at runtime; the filesystem adapter is always available.
Inspired by Andrej Karpathy's LLM Wiki. Markdown is the source of truth; the compiler turns structure into a graph; MCP exposes it.
git clone --depth 1 https://github.com/2233admin/obsidian-llm-wiki.git
cd obsidian-llm-wiki && ./setup # --host claude | codex | opencode | geminiWindows (PowerShell):
git clone --depth 1 https://github.com/2233admin/obsidian-llm-wiki.git
cd obsidian-llm-wiki; .\setup.ps1The setup script extracts a 1.6 MB skill bundle into your host's skills directory, prints the .mcp.json snippet to paste into your agent config, and exits. After restart, your agent picks up the new MCP server and the six /vault-* personas. The cloned repo can then be deleted — the installed skill is self-contained. If the one-liner breaks, docs/INSTALL.md has the per-host paths and the manual recipe.
Any MCP-compatible host:
| Host | Command | Status |
|---|---|---|
| Claude Code | ./setup --host claude |
primary target, fully exercised |
| Codex CLI | ./setup --host codex |
path configured, smoke-tested |
| OpenCode | ./setup --host opencode |
path configured, smoke-tested |
| Gemini CLI | ./setup --host gemini |
path configured, smoke-tested |
Anything else speaking stdio MCP transport should work — the setup script only copies skills into the right directory and prints the .mcp.json snippet. If your host reads MCP config from somewhere else, paste the snippet there by hand.
Cold start -- no vault context:
/vault-librarian what do I know about attention heads
Warm start -- specify a note you have:
/vault-librarian explain [[retrieval-augmented-generation]] in the context of my other notes on LLMs
Format-specific -- you want a list, not prose:
/vault-historian what decisions did I make about training data between January and March 2026
Iterate -- refine an answer:
/vault-curator find all orphan notes and stale notes in my vault that have not been updated in 90 days
Each persona is an opinionated prompt over the same 40-operation MCP tool set.
| Name | What it does | Primary MCP tools |
|---|---|---|
| vault-librarian | reads, searches, cites from the vault | vault.search, vault.read, vault.list |
| vault-architect | compiles concept graph, suggests refactors | vault.graph, vault.backlinks, compile.run |
| vault-curator | finds orphans, dead links, duplicates, stale notes | vault.lint, vault.searchByTag, vault.search |
| vault-teacher | explains a note in context of its neighbors | vault.backlinks, vault.read, vault.graph |
| vault-historian | answers what you were thinking on date X | vault.searchByFrontmatter, vault.stat, vault.search |
| vault-janitor | proposes cleanups, dry-run by default | vault.lint, vault.delete (dry), vault.rename (dry) |
Your markdown files -- with wikilinks [[like this]], aliases, frontmatter tags, and mtime -- are the source of truth. The compiler runs once and produces a concept graph (nodes = notes, edges = links and semantic relationships). The MCP server exposes this graph as tools: vault.search, vault.backlinks, vault.graph, and 40+ more.
When Claude Code (or any MCP-compatible agent) runs /vault-librarian, it calls vault.search and vault.read directly. The agent gets citations -- not guesses.
- No embeddings required at small scale. Optional pgvector-backed semantic search via the
memUadapter. - No database. Filesystem-only by default; a compiled graph is cached as plain JSON alongside the vault.
- No Obsidian required at runtime. The
filesystemadapter is always available. Obsidian is an optional adapter if you want live plugin-API features via a WebSocket bridge.
The wiki has the long-form answers. Eight pages, any order.
| Page | Answers |
|---|---|
| Rationale | Why this exists. Why not just grep, not just an Obsidian plugin, not just a vector DB, not just a long-context LLM. Covers the product drift. |
| Architecture | Four-layer system diagram. Request lifecycle (8 steps, /vault-librarian to cited answer). Extension points. |
| Adapter-Spec | Adapter contract, capability matrix, fan-out and ranking, failure modes, recipe for a fifth adapter. |
| Compile-Pipeline | What each stage produces, where the graph lives on disk, performance reference points. |
| Persona-Design | Six user-facing personas vs seventeen underlying skills. The design discipline that keeps them from collapsing into one generic agent. |
| Security-Model | Dry-run default, protected paths, preflight gates, bearer-token transport, what this explicitly does not secure. |
| Recipes | Content collectors (Feishu, Gmail, Linear, X, WeChat, and more) that land external sources into the vault. |
| FAQ | Does it need Obsidian running? How big a vault? Why dry-run? First-draft answers, expands as questions come in. |
- Does not understand code in your notes -- it indexes text, wikilinks, and structure. For AST-level code reasoning, enable the optional
gitnexusadapter. - Does not sync bidirectionally with Obsidian in real time -- the WebSocket adapter requires Obsidian to be running.
- Does not replace a vector database for semantic similarity at scale -- enable the optional
memUadapter for that. - The split between this repo (headless MCP) and its sibling
obsidian-vault-bridge(Obsidian plugin) is still settling. See the Rationale page for the drift discussion.
GPL-3.0. See LICENSE.