Obsidian Agentic RAG

Indexes your Obsidian vault and exposes 7 MCP tools to Claude Code. Gemini embeddings + Cohere reranking + BM25 + query expansion + RRF, running in one Docker container.

Prerequisites

• Docker (Docker Desktop or Colima)
• A Google Gemini API key — https://aistudio.google.com/apikey
• A Cohere API key — https://dashboard.cohere.com/api-keys
• Claude Code

Setup (5 steps)

# 1. Clone
git clone https://github.com/fsafey/obsidian-agentic-rag.git
cd obsidian-agentic-rag

# 2. Paste API keys
cp .env.example .env
$EDITOR .env

# 3. Install (builds the container, starts it, waits for first index, registers MCP)
./setup.sh /absolute/path/to/your/obsidian/vault

# 4. Verify
./setup.sh verify

# 5. Restart Claude Code

The obsidian-rag MCP tools will appear natively in Claude Code after the restart.

MCP tools

Tool	Best for	Example
search_hybrid	Complex questions	"How does our pricing compare to competitors?"
search_semantic	Conceptual questions	"What's our go-to-market strategy?"
search_keyword	Exact terms, names, dates	"LGPD article 11", "meeting Q3"
search_files	Finding files by topic	"List all notes mentioning onboarding"
search_aggregate	Distribution over folders/tags/time	"Where do my writing-craft notes live?"
get_full_note	Reading a complete note	"Show me the compliance checklist"
list_topics	Vault navigation	"What topics do we have documented?"
reindex	After editing notes	"I just updated some notes"
rag_status	System health	"Is the RAG running?"

How search works

A query is first expanded by Gemini 3 Flash into roughly five paraphrases. Each variant is batch-embedded via gemini-embedding-2-preview (4096d) and run against both a ChromaDB cosine-similarity index and a BM25 keyword index. Results are merged with Reciprocal Rank Fusion (k=60, original query weighted 3x), then re-scored by Cohere rerank-v3.5. The top 10 are returned. Incremental indexing is MD5-hash based; only changed files are re-embedded.

Troubleshooting

• doc_count stays at 0 — check docker logs obsidian-rag --tail 100 for Gemini API errors. Wrong/missing GEMINI_API_KEY is the usual cause.
• MCP tools don't appear in Claude Code — run ./setup.sh verify. If it passes, you haven't restarted Claude Code since registration. Quit completely, not just close the window.

Configuration

All runtime knobs (models, rerank toggle, query expansion toggle) live in docker-compose.yml under environment:. To change the embedding model, edit EMBED_MODEL, then:

docker compose down
docker volume rm obsidian-agentic-rag_obsidian-rag-data
./setup.sh /absolute/path/to/your/vault

The volume wipe is required because embedding dimensions may differ between models.

Not included

The repo also contains scripts/auto_tag.py, a UMAP+HDBSCAN+Gemini vault-tagging pipeline. It is not wired into setup or search, mutates vault frontmatter in place, and is for power users. Run at your own risk.

License

MIT — see LICENSE.