Obsidian Vault Rag Assistant

Obsidian Vault RAG Knowledge Assistant

Ask questions in natural language; get answers grounded in an Obsidian vault, with citations you can open and verify. Local embeddings, a numpy vector store, Claude *or* any OpenAI-compatible model for generation, one tool-use loop for multi-hop questions.

Quickstart (5 commands)

python -m venv .venv && .venv/Scripts/activate     # Windows (source .venv/bin/activate on POSIX)
pip install -r requirements.txt
python index.py --vault ./demo_vault               # ~15s: 27 notes -> 108 chunks
cp .env.example .env                               # then set ONE key; skip for extractive mode
python -m uvicorn app:app                          # http://127.0.0.1:8000

First model load takes ~1 minute (downloads/loads `all-MiniLM-L6-v2`, then cached). Point `--vault` at any Obsidian vault — the indexer is safe against hostile directory shapes (see *Indexer safety* below).

Architecture

vault/*.md
  -> index.py: walk (deny-list) -> dedup (content hash) -> chunk (heading-aware,
                180 words / 30 overlap, token-budget splitter) -> MiniLM embed
                -> vectors.npz + chunks.jsonl + meta.json
  -> app.py (FastAPI):
      POST /ask     cosine top-5 (numpy matmul) -> LLM -> answer + resolved citations
                    top score < 0.27 -> "not in this vault" (no LLM call)
      POST /agent   tool loop (max 8 turns): search_vault / read_note / list_by_tag
      GET  /healthz index stats + provider/model auth probe
      GET  /        chat UI (single static/index.html)

Providers

One key, either kind. Anthropic wins if both are set; with neither the app runs in **extractive** mode (top chunks verbatim, clearly labelled — `/agent` returns 503 because a model has to drive the tools).

	MY_ANTHROPIC_KEY	LLM_API_KEY (OpenAI-compatible)
Endpoint	pinned api.anthropic.com	LLM_BASE_URL — OpenRouter, NVIDIA Build, vLLM, LM Studio
Citations	native: docume