Connect your Obsidian vault to Claude with powerful local RAG capabilities.
obsidian-rag
A Claude Code plugin that connects your Obsidian vault to Claude through 18 MCP tools, 13 skills, and 2 specialized agents. Semantic search is powered by local embeddings (all-MiniLM-L6-v2) with a LanceDB vector store — everything runs locally with no external API calls.
Features
- Full vault CRUD — read, create, append, move, and edit notes with section-level precision
- Local RAG pipeline — semantic search across your entire vault using local embeddings
- Incremental indexing — only re-embeds changed files, with automatic reindexing after writes
- Daily notes — create, read, and append to daily notes with timestamped log entries
- Link graph — traverse outgoing links, backlinks, and find broken wikilinks
- Frontmatter management — safe YAML frontmatter updates with schema validation
- Skills and agents — higher-level workflows for research, organization, and vault maintenance
Installation
From the marketplace
In Claude Code, run:
/plugin marketplace add thoreinstein/claude-plugins
/plugin install obsidian-rag@thoreinstein-plugins
Manual
git clone https://github.com/thoreinstein/obsidian-rag.git ~/.claude/plugins/obsidian-rag
cd ~/.claude/plugins/obsidian-rag
npm install
The built artifact (dist/index.js) is committed to the repo, so no build step is needed. Native dependencies are automatically installed on first session start when using the marketplace install.
Quick start
- Set your vault path — use
/vault or set OBSIDIAN_VAULT_PATH in your environment
- Build the index — run
/index to build the vector index (incremental updates happen automatically)
- Start using it — ask questions about your notes, create new ones, or use any of the skills below
Tools
Reading and searching
| Tool | Description |
|---|
obsidian_read_note | Read the full content of a note |
obsidian_list_notes | List markdown files in the vault or a subdirectory |
obsidian_search_notes | Search notes by keyword (filename and content) |
obsidian_rag_query | Semantic search across the indexed vault |
obsidian_get_daily_note | Get or create today's daily note |
Writing and editing
| Tool | Description |
|---|
obsidian_create_note | Create a new note (auto-creates parent directories) |
obsidian_append_note | Append text to an existing note |
obsidian_append_daily_log | Append a timestamped entry under a daily note heading |
obsidian_replace_section | Replace the body under a heading |
obsidian_insert_at_heading | Insert content at the beginning or end of a section |
obsidian_replace_in_note | Replace the first occurrence of a text string |
obsidian_update_frontmatter | Update YAML frontmatter (single or batch) |
obsidian_move_note | Move or rename a note |
Links and graph
| Tool | Description |
|---|
obsidian_get_links | Get all outgoing [[wikilinks]] from a note |
obsidian_get_backlinks | Find all notes that link to a given note |
obsidian_get_broken_links | Find wikilinks pointing to non-existent notes |
Index and config
| Tool | Description |
|---|
obsidian_rag_index | Build or rebuild the vector index (incremental by default) |
obsidian_set_vault | Set the default vault path |
Skills
Skills are higher-level workflows invoked with /skill-name in Claude Code.
Core skills
| Skill | Description |
|---|
/obsidian-companion | Guides tool selection and writing strategy for vault operations |
/research | Deep vault research — chains semantic search, note reading, and link traversal to synthesize answers with citations |
/journal | Daily note workflows — view today's entry, add logs, weekly review |
/index | Build or rebuild the vector index |
/vault | Set or change the vault path |
/search | Find notes by keyword or filename |
/links | Explore connections between notes (outgoing links, backlinks) |
Advanced workflow skills
| Skill | Description |
|---|
/cross-linker | Find unlinked mentions across the vault and insert missing [[wikilinks]] with confidence scoring |
/vault-lint | Health audit — frontmatter compliance, stale content, orphaned notes, MOC coverage gaps |
/wiki-ingest | Distill external sources (PDFs, markdown, transcripts) into vault-native notes with provenance tracking |
/compound | Promote cross-project knowledge to a global folder via semantic clustering |
/moc-update | Suggest which Maps of Content a new note belongs in |
/link-audit | Audit link health — broken wikilinks, orphaned notes, semantic link suggestions |
Agents
Agents are specialized subprocesses launched automatically when a task requires deep, multi-step work.
| Agent | Purpose |
|---|
| researcher | Deep vault research with semantic search chaining, full note reading, link following, and backlink discovery. Synthesizes findings with citations. |
| librarian | Vault organization and maintenance — audits folder structure, cleans up frontmatter, finds orphan notes, and suggests reorganization. |
Configuration
Environment variables
| Variable | Default | Description |
|---|
OBSIDIAN_VAULT_PATH | — | Default vault path (overrides config file) |
OBSIDIAN_RAG_MIN_CHUNK_CHARS | 40 | Minimum chunk size in characters |
OBSIDIAN_RAG_MAX_CHUNK_CHARS | 1800 | Maximum chunk size in characters |
OBSIDIAN_RAG_TARGET_CHUNK_CHARS | 700 | Target chunk size for merging small chunks |
OBSIDIAN_RAG_EMBED_BATCH_SIZE | 48 | Number of chunks to embed per batch |
Data storage
When installed as a plugin, all state is stored in the plugin's persistent data directory (~/.claude/plugins/data/{id}/). For development or CLI usage, falls back to ~/.
| File | Purpose |
|---|
.obsidian-rag.config.json | Vault path configuration |
.obsidian-rag-lancedb/ | LanceDB vector store |
.obsidian-rag-file-hashes.json | MD5 hashes for incremental indexing |
Optional vault-level config
| File | Purpose |
|---|
.obsidian-rag-schema.json | Frontmatter validation schema (enforced by PreToolUse hook) |
.manifest.json | Ingest tracking and source provenance (used by /wiki-ingest) |
Hooks
The plugin registers three hooks that run automatically:
| Hook | Trigger | What it does |
|---|
| Dependency install | Session start | Installs native deps if package.json has changed |
| Session init | Session start | Reports vault status and runs incremental reindex |
| Reindex note | After note writes | Re-embeds the modified note to keep the index fresh |
| Validate frontmatter | Before note creation | Blocks creation if required frontmatter fields are missing |
Architecture
Obsidian vault (markdown files)
|
[chunking] ── splits notes into semantic chunks
|
[embedder] ── all-MiniLM-L6-v2 via @xenova/transformers (local)
|
[LanceDB] ── vector store with incremental updates
|
[MCP server] ── 18 tools exposed over stdio
|
Claude Code ── skills, agents, and hooks
The MCP server runs over stdio and also supports a one-shot CLI mode used by hook scripts. The embedding model runs entirely locally — no data leaves your machine.
Development
npm install # Install dependencies
npm run build # Bundle with esbuild
npm run type-check # TypeScript validation
npm test # Run tests with vitest
Key constraints
- onnxruntime-node pinned to 1.14.0 — required by
@xenova/transformers 2.17.x; do not upgrade
- Native deps externalized —
@lancedb/lancedb, onnxruntime-node, and sharp are excluded from the esbuild bundle and load from node_modules at runtime
- dist/ is committed — the built artifact is checked in so the plugin works after
clone + npm install with no build step
- Dependency placement is intentional — bundled deps are in
devDependencies (esbuild bakes them in); externalized native deps are in dependencies (loaded from node_modules)
Project structure
.claude-plugin/plugin.json # Plugin manifest (MCP server config, hooks)
src/
index.ts # MCP server and tool implementations
utils.ts # Wikilink extraction, section editing, frontmatter ops
rag/
store.ts # VaultIndexer (LanceDB vector store)
embedder.ts # Embedding pipeline (@xenova/transformers)
chunking.ts # Text chunking module
skills/ # 13 skill definitions
agents/ # 2 agent definitions (researcher, librarian)
scripts/ # Hook shell scripts
test/ # Vitest test suite
dist/index.js # Built artifact (committed)
License
MIT