QMD Vault Search

Search your Obsidian vault with its own QMD index. No runtime dependencies.

Features

• Fast hybrid search: keyword and semantic results in one list.
• Deep search with LLM query expansion, on demand.
• A related-notes panel that follows the note you are on.
• The index refreshes at startup and once a day.

Requirements

• Obsidian 1.13.0 or newer, desktop only. Tested on Linux (Flatpak and native) and macOS; Windows is untested.

• qmd installed, and an index inside the vault that contains the vault. In the vault folder, run:

  qmd init
  qmd collection add .
  

  qmd init alone creates an empty index; the plugin then says that it has no collections.

qmd installed with a Node version manager (fnm, nvm, volta, asdf, mise): the plugin also looks in the manager's default folders. If the status bar still says it can't find qmd, set Path to qmd in the settings. On macOS, Obsidian started from the Dock or Finder doesn't get the PATH set in your shell profile.

Installation

From the community directory (recommended)

1. Open Settings → Community plugins and turn on community plugins if asked.
2. Select Browse, search for QMD Vault Search, then select Install and Enable.

You can also open the plugin's page: community.obsidian.md/plugins/qmd-vault-search.

Manually

1. Download main.js, manifest.json and styles.css from the latest release.
2. In Settings → Community plugins, select the folder icon next to Installed plugins. This opens <vault>/.obsidian/plugins/.
3. Create a folder named qmd-vault-search there and put the three files in it.
4. Select the reload icon next to Installed plugins, then enable QMD Vault Search.

Beta versions: install BRAT and add dingzy53/obsidian-qmd.

Update or remove: select Check for updates or Uninstall in Settings → Community plugins.

Upgrading from the qmd-search or obsidian-qmd folder: the plugin ID is now qmd-vault-search. Copy data.json from the old plugin folder into the new one to keep your settings, then delete the old folder.

How it works

• The vault's own index. The plugin runs qmd inside the vault folder, so qmd uses <vault>/.qmd/index.sqlite and <vault>/.qmd/index.yml (created with qmd init and qmd collection add .). If that index cannot be found the plugin says so and stops; it never falls back to the global index.
• A warm server. While Obsidian is open the plugin keeps one qmd mcp --http process running so the embedding model stays loaded. A fused keyword + vector search then takes roughly 0.3–0.7 s instead of 10+ s per search through the CLI. The server stops when the plugin is disabled or Obsidian closes.
• Scheduled refresh. About 20 seconds after launch, and once a day after a set hour, the plugin runs qmd update and, if anything changed, qmd embed. When nothing changed it does nothing else.

Usage

Each result shows the note name, its folder, the matched section and an excerpt taken from the note itself (math rendered, never cut mid-formula).

Keys in the search box

Mouse: click opens, Ctrl-click or middle-click opens a new tab, resting on a row in a sidebar panel shows a page preview (after about 2 s, or at once with Ctrl held), right-click gives a menu, and a row can be dragged into a note to make a link.

Query syntax: "exact phrase" and -excluded work for the keyword half of the search. Folder filter: type a folder in the field under the search box.

Excluding folders: right-click a folder and choose Exclude from qmd index, or use Excluded folders in settings. Its notes leave search after a short refresh. Their text stays in the index file until you press Purge.

The status bar item QMD ● shows the state (green ready, yellow starting or indexing, red problem). Click it to update the index, restart the server or open settings.

Settings

All settings appear in Obsidian's settings search.

Privacy and security

• Network: the plugin talks only to the qmd server it starts itself, over HTTP on localhost. The plugin sends nothing to the internet. qmd downloads its embedding and query models the first time they are needed; see the qmd documentation.
• Files outside the vault: the plugin runs the external qmd program, which you install yourself. To find it, the plugin looks in the usual install folders (~/.local/bin, ~/.bun/bin, ~/.cargo/bin, /usr/local/bin, /opt/homebrew/bin, /usr/bin, the default folders of fnm, nvm, volta, asdf and mise, and npm's global folder on Windows) and on PATH. qmd keeps its models and cache in your home directory. If you set Index location to a folder outside the vault, the index is read from and written there.
• Running programs (child_process): the plugin starts only the qmd binary, with fixed arguments and never through a shell: the search server, searches, update, embed, status and cleanup, plus which/where to locate qmd. Under Flatpak these run on the host through flatpak-spawn --host, because qmd is installed outside the sandbox.
• Direct file access (fs): the index lives in a hidden .qmd folder, or outside the vault if you choose, which Obsidian's vault API does not reach. The plugin uses Node's fs only to read .qmd/index.yml, to rewrite its ignore list (see Config file), to check whether the qmd binary or /.flatpak-info exists, and to list nvm's installed Node versions. Notes are read through Obsidian's vault API.
• Config file: excluding or including a folder, or renaming an excluded one, edits the ignore list in .qmd/index.yml. Nothing else in that file is changed.
• Clipboard: the plugin only writes to the clipboard, never reads it. It writes a link to a note when you choose Copy link on a result, or when you insert a link with no note open.
• No telemetry, ads, accounts or payments.

Limitations

• .qmd/index.sqlite changes whenever the index is refreshed after notes changed. While the server runs, the newest writes sit in index.sqlite-wal and are folded into index.sqlite when the server stops or restarts.
• A fused search draws on the top 20 keyword and top 20 semantic hits. With a folder filter the plugin tops the list up with a wider keyword search.
• Reranking and query expansion are CPU-bound LLM work; only fast search is instant.
• Until you purge, the vectors of excluded notes still take up places among the nearest matches, so semantic results can be thinner. Including a folder again before a purge needs no re-embedding.

Development

npm install
npm run dev      # watch build
npm run build    # type-check and bundle to main.js
npm run lint     # the same eslint-plugin-obsidianmd rules the community-plugin review runs
npm test
QMD_PLUGIN_DIR=<vault>/.obsidian/plugins/qmd-vault-search npm run deploy   # build and copy into a vault

Then reload the plugin: obsidian plugin:reload id=qmd-vault-search. See AGENTS.md for design notes.

Releasing

npm version patch   # bumps package.json, manifest.json and versions.json, commits and tags (no "v" prefix, see .npmrc)
git push --follow-tags

The tag triggers the Release workflow. It lints, tests and builds, then attaches main.js, manifest.json and styles.css to a GitHub release. Never upload a main.js you built locally: the community directory rebuilds the tagged source with npm run build and checks that the result matches the release.

Community directory. The plugin is submitted once at community.obsidian.md, from the plugin's page there. Before tagging, run Review branch on main to preview the automated review (manifest, release assets, source code, build verification). After the first submission, every new GitHub release is picked up automatically, or straight away with Request review.

License

MIT © 2026 Ding Zheng Yuan