obsidian-notes-rag: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

obsidian-notes-rag is an MCP (Model Context Protocol) server that provides semantic search over Obsidian notes. It uses OpenAI embeddings by default (or Ollama/LM Studio for local processing) with sqlite-vec for vector storage.

PyPI: https://pypi.org/project/obsidian-notes-rag/ GitHub: https://github.com/proofgeist/obsidian-notes-rag

Commands

# Install dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Type checking
uv run pyright

# Interactive setup wizard
uv run obsidian-rag setup

# Index vault (manual refresh)
uv run obsidian-rag index

# Run the MCP server (stdio transport)
uv run obsidian-rag serve

# Watch vault for changes
uv run obsidian-rag watch

# Search from CLI
uv run obsidian-rag search "query"
obsidian-rag similar "Path/To/Note.md"
obsidian-rag context "Path/To/Note.md"

Architecture

Data Flow

Obsidian Vault → VaultIndexer → Embedder (OpenAI/Ollama/LMStudio) → VectorStore (sqlite-vec)
                                                                          ↓
MCP Client ← MCPServer (mcp 2.x) ← search_notes/get_similar/etc.

Key Components (src/obsidian_rag/)

• config.py: Config dataclass, load_config()/save_config() for TOML config file, cross-platform paths via platformdirs
• indexer.py: VaultIndexer scans markdown files, chunk_markdown() uses Chonkie RecursiveChunker with markdown-aware rules, OpenAIEmbedder/OllamaEmbedder/LMStudioEmbedder generate embeddings, create_embedder() factory selects provider
• store.py: VectorStore wraps sqlite-vec with KNN vector search, two tables (chunks metadata + chunks_vec virtual table), handles upsert/delete by file path. Thread-safe (check_same_thread=False + threading.Lock).
• server.py: MCPServer (mcp 2.x decorator API, successor to FastMCP) exposing 5 tools: search_notes, get_similar, get_note_context, get_stats, reindex
• watcher.py: VaultWatcher uses watchdog with debouncing (default 2s) to incrementally re-index on file changes
• cli.py: Click-based CLI with setup wizard, --provider option, commands for indexing, searching, similar, context, watching, and service management