Vault Retrieval

Retrieval over your own vault — related notes, semantic search, and grounded chat — running locally and offline.

Vault Retrieval turns your notes into a searchable knowledge base without sending anything to the cloud. It reads a small embedding index that ships with your vault and answers three questions: What else have I written about this? Where did I say something like that? What does my vault know about X? Generation (chat) runs against a local LLM endpoint you control.

Features

• Related notes — a side panel ranks the notes most similar to the one you're reading. Cosine similarity over a compact note-level index, computed on-device — works fully offline, including on mobile.
• Semantic search — find notes by meaning, not just keywords.
• Grounded RAG chat — ask your vault a question and get an answer grounded in retrieved notes, streamed token-by-token from your local LLM. An editable live-context panel shows exactly which notes feed the answer, with source chips that link back.
• Visible thinking, with an off switch — for reasoning models, the live "💭 thinking" stream appears in a collapsible block above the answer and folds away once it arrives (and is never sent back into the conversation history). A toggle suppresses thinking when you want faster answers — via cross-server-portable hints — and a settings test tells you whether your model actually honours it.
• Model capability hints — settings show, best-effort, whether the selected chat model supports vision and/or thinking, so you can pick the right one. Each endpoint has an inline connection test, and the model pickers populate from the server.
• Live indexing — notes are re-embedded on save; edits made offline queue up and catch up automatically on reconnect.
• Smart Apply — restructure a note into a template (opt-in) — pick a template and a local LLM reorganises a messy note into its sections, routing your original blocks under the right headings. It never invents content — a diff gate shows exactly what moves where before you apply, and the body is rebuilt from your own bytes. Templates self-describe through %% guidance comments, and a relevance-ranked template list (cosine over the same index — reusing the stored vectors, no re-embedding) preselects the best fit and updates live as you switch notes. Enable it under Settings → Smart Apply.
• Reformat a selection — select any block of text and run Abschnitt umformatieren (command palette or editor context menu) to reshape it. Mechanical transforms (transpose a table, table → list, wrap in a callout) apply instantly, no LLM involved. Shape-changing transforms (→ list, → prose, → table, → Mermaid diagram, or your own free-text instruction) stream a preview from your local chat LLM that you review and can regenerate before applying. You can also launch every transform from the Umformatieren tab in the sidebar, which shows what is currently selected and greys the buttons out (with the reason) when it cannot run.

Requirements

• Obsidian 1.13+ (desktop or mobile).
• An embedding index in <vault>/_vaultrag/ (default path; configurable in settings and hidden in the file explorer by default) — produced by your indexing backend and synced with the vault. The related-notes panel and semantic search need only this index; no running server.
• For chat (and live re-indexing): an OpenAI-compatible local LLM endpoint (Ollama for embeddings, LM Studio for chat). New to local LLMs? The local LLM setup guide walks you through it. Configurable in settings; nothing leaves your machine.

Install

Community Plugins

In Obsidian, open Settings → Community plugins → Browse, search for Vault Retrieval, then install and enable it.

Manual

Download main.js, manifest.json and styles.css from the latest release, drop them into <vault>/.obsidian/plugins/vault-retrieval/, then enable Settings → Community plugins → Vault Retrieval.

BRAT (beta)

Add the GitHub mirror johannes-kaindl/vault-rag in the BRAT plugin to track pre-release builds.

From source

git clone https://codeberg.org/jkaindl/vault-rag
cd vault-rag
npm install
npm run build      # → main.js
# copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/vault-retrieval/

Usage

1. Enable the plugin and open a note. The Related notes panel (ribbon: 🔍) populates automatically.
2. Open Semantic search (ribbon: 🔭) to query the vault by meaning.
3. Open Vault Chat (ribbon: 💬), point the chat endpoint at your local LLM in settings, and ask away. Edit the live-context list to control which notes ground the answer.
4. (Optional) Enable Smart Apply in settings, then open its cockpit (ribbon: 🪄). Pick a template from the relevance-ranked list and apply it to the active note — review the diff, then accept, re-generate, or pick another template.
5. Select a block of text, then run Abschnitt umformatieren from the command palette or the editor right-click menu — or open the Umformatieren tab in the sidebar and click a transform. Mechanical ones apply immediately; LLM ones open a streamed preview to review before applying. Reformatting needs editing mode; in reading mode the buttons stay disabled and say so. If you edit the note while a preview is open, the replacement is refused rather than applied at the wrong spot.

Configuration

Endpoint tip: enter the base URL without a trailing /v1 — the plugin appends it. Both forms are accepted.

How it works

Your indexing backend exports a portable note-level Matryoshka-256 int8 mini-index (~1.4 MB) into <vault>/_vaultrag/. The plugin loads it and runs brute-force cosine locally — no daemon, no VPN, no on-device LLM needed for retrieval. Only chat talks to an LLM, over an endpoint you configure. The portable index is what makes retrieval work identically across all your synced devices.

Architecture, module layout and contributor conventions live in AGENTS.md.

MCP server (use your index from Claude Code & other agents, desktop only)

The plugin's embedding index doubles as a retrieval backend for MCP clients (Claude Code, OpenClaw, …). An in-plugin HTTP server (Streamable HTTP, loopback-only) exposes three read-only tools:

Enable it in the plugin settings under "MCP-Server" (desktop only — the toggle and server are disabled on mobile). The server binds to 127.0.0.1 on a configurable port (default 8123) and requires a Bearer token on every request. The settings section has a "copy command" button that generates the registration command for you, e.g.:

claude mcp add --transport http vault-retrieval http://127.0.0.1:8123/mcp \
  --header "Authorization: Bearer <token>"

Configuration (endpoints, index folder, excludes) is read from the plugin's own settings — no separate config file. The server only runs while Obsidian is open and picks up index changes live (reloads whenever the plugin rewrites the index). One server instance per vault. The server never writes to your vault.

Note: read_note enforces exclude prefixes case-insensitively (safe on case-insensitive filesystems like APFS/NTFS), while search/related filter result paths case-sensitively — they expose only paths and scores, never content.

Related

Image transcription (handwriting/screenshots → Markdown) lives in the sibling plugin image-to-markdown.

Contributing

Issues and pull requests are welcome on Codeberg. The project is test-driven — every change ships with tests (npm test), and larger features go through a brainstorm → spec → plan → TDD flow (docs/superpowers/). See AGENTS.md for conventions.

License

• Code: GNU Affero General Public License v3.0 or later (LICENSE). A commercial dual-license is available on request if the AGPL's copyleft doesn't fit your use case.
• Documentation & text: Creative Commons Attribution-ShareAlike 4.0 (LICENSE-DOCS).

Copyright © 2026 Johannes Kaindl.