Obsidian Rag

Fully local RAG over an Obsidian (or any markdown) vault, powered by LM Studio. Nothing leaves your machine.

Two ways to use it:

• obsidian-rag — a terminal REPL: ask questions, get answers grounded in your notes with source citations.
• obsidian-rag-mcp — an MCP server for the LM Studio GUI: the chat model gets a search_notes tool and answers from your vault, inside the app.

Indexing is incremental: only new or edited files are re-embedded on each run.

Prerequisites

1. LM Studio with the local server running (Developer tab → Start Server, default http://localhost:1234).
2. Two models loaded:
   • a chat model (e.g. any Gemma / Llama / Qwen instruct model)
   • an embedding model (e.g. nomic-embed-text-v1.5)
3. Python ≥ 3.11 and uv (or pipx).

Install

uv tool install git+https://github.com/shirokoweb/rag-obsidian-lmstudio
# or: pipx install git+https://github.com/shirokoweb/rag-obsidian-lmstudio

Use the terminal REPL

obsidian-rag --docs-dir ~/path/to/your/vault

Chat:  google/gemma-4-e4b
Embed: text-embedding-nomic-embed-text-v1.5
Indexed 317 chunks from /Users/you/vault

Ask a question (blank line or Ctrl-D to quit).
? What is the CIA triad?

The CIA triad is a model that helps organizations consider risk ...

  sources: Module 2/25. Explore the CIA triad.md, ...
  top score: 0.830

Use inside LM Studio (MCP)

Add the server to LM Studio's mcp.json (Program tab → Install → Edit mcp.json):

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "obsidian-rag-mcp",
      "env": {
        "RAG_DOCS_DIR": "/Users/you/path/to/your/vault"
      }
    }
  }
}

Then ask the chat model anything about your notes — it calls search_notes and answers grounded, with source filenames.

If LM Studio can't find the command, use the absolute path (which obsidian-rag-mcp) in the command field.

Configuration

CLI flags take precedence over environment variables.

Auto-detection picks the first loaded model whose id contains embed as the embedder and the first other model for chat. With several chat models loaded, set RAG_CHAT_MODEL explicitly.

The embedding cache lives in your OS user-cache directory (e.g. ~/Library/Caches/rag-obsidian-lmstudio on macOS) — never inside your vault. Deleting it is always safe; it will be rebuilt.

Troubleshooting

Privacy & security notes

• All traffic goes to your configured LM Studio URL (localhost by default); there are no other network calls, no telemetry.
• The cache uses plain JSON + NumPy .npz — no pickle, nothing executable.
• The tool only ever reads your vault; it never writes into it.

Development

git clone https://github.com/shirokoweb/rag-obsidian-lmstudio
cd rag-obsidian-lmstudio
uv sync --all-extras
uv run pytest                 # tests
uv run ruff check . && uv run ruff format --check .
uv run mypy src               # typecheck

See SPEC.md for design decisions. MIT license.