Skip to content
Back to search

obsidian-hybrid-search

Hybrid search for Obsidian vaults via plugin, CLI, and MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/flowing-abyss/obsidian-hybrid-search with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/flowing-abyss/obsidian-hybrid-search'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/flowing-abyss--obsidian-hybrid-search/badge.svg)](/listings/flowing-abyss--obsidian-hybrid-search)

HTML

<a href="/listings/flowing-abyss--obsidian-hybrid-search"><img src="/api/listings/flowing-abyss--obsidian-hybrid-search/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g obsidian-hybrid-search

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 532 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Obsidian Hybrid Search
  2. [![npm version](https://img.shields.io/npm/v/obsidian-hybrid-search)](https://www.npmjs.com/package/obsidian-hybrid-search)
  3. [![Tests](https://github.com/flowing-abyss/obsidian-hybrid-search/actions/workflows/ci.yml/badge.svg)](https://github.com/flowing-abyss/obsidian-hybrid-search/actions)
  4. [![Total downloads](https://badgen.net/npm/dt/obsidian-hybrid-search)](https://www.npmjs.com/package/obsidian-hybrid-search)
  5. <p align="center">
  6. <img src="assets/banner.png" alt="Obsidian Hybrid Search explains hybrid retrieval from Obsidian notes" />
  7. </p>
  8. Your Obsidian vault already contains your best thinking. Obsidian Hybrid Search makes that thinking easier to find, reuse, and bring into AI-assisted work.
  9. It gives your vault one retrieval engine and three practical ways to use it. The native [Obsidian plugin][obsidian-plugin] gives you fast search, previews, similar notes, link discovery, and graph views while you write. The MCP server lets AI agents search and read your notes as tool calls. The CLI gives power users the same engine for indexing, filtering, reranking, reading, and scripting.
  10. The search understands how real vaults are built. It combines semantic search, BM25 full text, fuzzy title and alias matching, tags, folders, frontmatter, wikilinks, backlinks, and similar-note lookup. You can search by idea, phrase, title, relationship, or metadata without remembering the exact words you wrote.
  11. That turns Obsidian into a stronger personal knowledge system and a better starting point for AI work. Agents can begin from your own notes, pull cited context from source files, follow related material, and work with knowledge you already trust. OHS runs locally by default with SQLite, FTS5, sqlite-vec, RRF ranking, and optional OpenAI-compatible embedding APIs.
  12. ## Search quality
  13. Evaluated on the [Obsidian Help vault](eval/README.md) (171 notes, 58 queries, local models):
  14. | Configuration | nDCG@5 ↑ | MRR ↑ | Hit@1 ↑ | Avg query (ms) ↓ | Model download ↓ |
  15. | :--------------------------------------------------------------------- | --------: | --------: | --------: | ---------------: | ---------------: |
  16. | [OHS Qwen, rerank](eval/results/qwen3-embedding-0.6b-rerank.json) ¹ | **0.812** | **0.857** | 79.3% | 730 | ~980 MB |
  17. | [OHS Qwen, hybrid](eval/results/qwen3-embedding-0.6b-no-rerank.json) ¹ | 0.802 | 0.856 | **81.0%** | 38 | ~639 MB |
  18. | [OHS default, rerank](eval/results/baseline-rerank.json) ² | 0.779 | 0.837 | 77.6% | 718 | ~458 MB |
  19. | [OHS default, hybrid](eval/results/baseline-no-rerank.json) ² | 0.743 | 0.799 | 72.4% | **8** | **~117 MB** |
  20. | [QMD, rerank](eval/results/qmd-rerank.json) ³ | 0.727 | 0.735 | 60.3% | 12,308 | ~973 MB |
  21. | [QMD, full](eval/results/qmd.json) ³ | 0.713 | 0.706 | 55.2% | 25,306 | ~2.2 GB |
  22. | [QMD, hybrid](eval/results/qmd-hybrid.json) ³ | 0.685 | 0.703 | 60.3% | 14 | ~334 MB |
  23. ¹ GPU (Apple Silicon Metal, Ollama).
  24. ² CPU (Apple Silicon).
  25. ³ GPU (Apple Silicon Metal).
  26. Default uses `Xenova/multilingual-e5-small`; Qwen uses `qwen3-embedding:0.6b`. QMD was tested at [v2.8.3](https://github.com/tobi/qmd).
  27. [How to reproduce →](eval/COMPARISON.md) · [Full benchmark →](eval/README.md)
  28. ### Real knowledge-vault benchmark
  29. OHS is also evaluated on Andy Matuschak’s public evergreen notes, converted into an Obsidian vault with title-based note filenames, source URLs in frontmatter, local attachments, and `5,000+` internal note links across `1,357` notes.
  30. The curated golden set includes `78` hand-judged queries across known-item lookup, paraphrases, quote fragments, ambiguous topics, citation lookup, and multi-note evidence.
  31. Using the default local embedding model, OHS performs strongly on this dense note network.
  32. | Metric | Value |
  33. | --------- | --------- |
  34. | nDCG@5 | **0.721** |
  35. | nDCG@10 | 0.754 |
  36. | MRR | 0.875 |
  37. | Hit@1 | 0.795 |
  38. | Hit@5 | 0.962 |
  39. | Recall@10 | 0.972 |
  40. | AllRel@10 | 0.949 |
  41. The benchmark exercises retrieval over a highly connected real-world knowledge vault, including queries that do not simply repeat note titles.
  42. [Result JSON](eval/results/evergreen-notes-no-rerank.json) · [Reproduce and interpret →](fixtures/evergreen-notes/README.md)
  43. ### Large memory benchmark
  44. To test retrieval on a larger public dataset,
  45. [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned)
  46. was converted into a `22,419`-note Obsidian-style vault with `470` retrieval
  47. queries. Using `baai/bge-m3` embeddings, OHS ranked the answer-bearing notes
  48. strongly:
  49. | Metric | Value |
  50. | --------- | --------- |
  51. | nDCG@5 | **0.895** |
  52. | MRR | 0.920 |
  53. | Hit@1 | 0.889 |
  54. | Hit@5 | 0.968 |
  55. | Recall@10 | 0.950 |
  56. | AllRel@10 | 0.904 |
  57. For this benchmark, each query uses the LongMemEval-provided haystack as its
  58. search scope. That makes the result reproducible and easy to inspect query by
  59. query, while still exercising retrieval over a large generated memory vault.
  60. [Result JSON](eval/results/longmemeval-s-no-rerank.json) · [Reproduce and interpret →](fixtures/longmemeval-s/README.md)
  61. ## Features
  62. - **Hybrid search**
  63. - BM25 + fuzzy title + semantic embeddings, fused with RRF
  64. - **Alias search**
  65. - notes with `aliases:` in frontmatter are indexed and searchable by any alias; alias matches are boosted in BM25 (weight 5×) and fuzzy title scoring
  66. - **Four search modes**
  67. - `hybrid`, `semantic`, `fulltext`, `title` (for text queries)
  68. - **Similar note lookup**
  69. - pass `--path` to find semantically related notes using stored chunk embeddings, with a title + content fallback
  70. - **Graph traversal**
  71. - `--path --related` shows linked notes at configurable depth; filter by `--direction outgoing|backlinks|both`
  72. - **Links & backlinks**
  73. - every result includes outgoing links and backlinks
  74. - **Scope filtering**
  75. - restrict to subfolder(s); supports multiple values and exclusions (`-notes/dev/`)
  76. - **Tag filtering**
  77. - filter by tag(s); supports multiple values and exclusions (`-category/cs`)
  78. - **Snippet control**
  79. - `--snippet-length` sets the context window; empty snippets always fall back to note content
  80. - **Extended output**
  81. - `--extended` adds a TAGS/ALIASES column to the CLI table showing frontmatter tags (`#tag`) and aliases
  82. - **Incremental indexing**
  83. - only re-indexes changed files; watches for edits in real time
  84. - **Multi-query fan-out**
  85. - pass multiple queries at once (`ohs "q1" "q2"` or `queries[]` in MCP); results are merged via RRF, so a note that ranks well in any one query floats to the top; useful when the note may use different vocabulary than the query
  86. - **Cross-encoder reranking**
  87. - `--rerank` re-scores results with `gte-multilingual-reranker-base` (ONNX int8, ~341 MB download once); improves precision for conceptual and multilingual queries; applied after multi-query merge
  88. - **Local embeddings**
  89. - works offline via `@huggingface/transformers` (no API key required); default model: Xenova/multilingual-e5-small, 100+ languages
  90. - **Remote embeddings**
  91. - OpenAI-compatible API (OpenRouter, Ollama, etc.)
  92. - **Note reading**
  93. - `read` fetches one or more notes by vault-relative path; returns full content with title, aliases, tags, links, and backlinks; on path miss returns top-3 fuzzy suggestions
  94. - **Ignore patterns**
  95. - exclude folders, extensions, or specific files
  96. - **Obsidian plugin**
  97. - native search modal inside Obsidian powered by the same CLI; see [obsidian-hybrid-search-plugin](https://github.com/flowing-abyss/obsidian-hybrid-search-plugin)
  98. ## Installation
  99. ```bash
  100. npm install -g obsidian-hybrid-search
  101. ```
  102. ## CLI usage
  103. ### Quick start
  104. The recommended setup is to set `OBSIDIAN_VAULT_PATH` once in `~/.zshrc` or `~/.bashrc`. This lets you run the CLI from any directory.
  105. ```bash
  106. export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
  107. ```
  108. Open a new terminal and index the vault once.
  109. ```bash
  110. ohs reindex
  111. ```
  112. You can now search from any directory.
  113. ```bash
  114. ohs "zettelkasten"
  115. ```
  116. ### Run from a vault
  117. Alternatively, run the CLI without an environment variable from any directory inside your vault. It finds the vault root by walking up to the nearest `.obsidian/` folder.
  118. ```bash
  119. cd /path/to/your/vault
  120. ohs reindex
  121. ohs "zettelkasten"
  122. ```
  123. From outside the vault, set `OBSIDIAN_VAULT_PATH` or pass `--db /path/to/vault/.obsidian-hybrid-search.db` explicitly.
  124. ### Optional remote embeddings
  125. By default, the CLI uses the local `Xenova/multilingual-e5-small` model. It works offline without an API key, downloads about 117 MB on first use, and supports more than 100 languages.
  126. To use a remote API, add its settings to your shell profile.
  127. ```bash
  128. export OPENAI_API_KEY="sk-..."
  129. # Override the default API base for another provider
  130. # export OPENAI_BASE_URL="https://openrouter.ai/api/v1" # OpenRouter
  131. # export OPENAI_BASE_URL="http://localhost:11434/v1" # Ollama (no key needed)
  132. # export OPENAI_BASE_URL="http://localhost:1234/v1" # LM Studio (no key needed)
  133. # Override the default text-embedding-3-small model
  134. # export OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
  135. ```
  136. ### Search modes
  137. The CLI supports four search modes called `hybrid`, `fulltext`, `semantic`, and `title`, plus graph traversal for linked notes. The commands below show how to use them, apply filters, rerank results, and control the output.
  138. ```bash
  139. # Hybrid search (default)
  140. ohs "zettelkasten atomic notes"
  141. # Fulltext BM25 search
  142. ohs "permanent notes" --mode fulltext
  143. # Fuzzy title search (fast, typo-tolerant)
  144. ohs "zettleksten" --mode title
  145. # Semantic / vector search
  146. ohs "how to build a knowledge graph" --mode semantic
  147. # Limit results and set a score threshold
  148. ohs "productivity systems" --limit 5 --threshold 0.3
  149. # Restrict to a subfolder
  150. ohs "daily review" --scope notes/periodic/
  151. ohs "daily review" --folder notes/periodic/ # alias for --scope
  152. # Restrict to multiple subfolders (OR)
  153. ohs "productivity" --scope notes/pkm/ --scope notes/2024/
  154. # Exclude a subfolder
  155. ohs "programming" --scope notes/ --scope -notes/archive/
  156. # Filter by tag
  157. ohs "productivity" --tag pkm
  158. ohs "machine learning" --tag note/basic/primary
  159. # Filter by multiple tags (AND include, exclude with -)
  160. ohs "learning" --tag pkm --tag work
  161. # Filter by frontmatter / properties (exact match, case-insensitive)
  162. ohs "notes" --frontmatter status:todo
  163. ohs "notes" --prop priority:high # --prop is alias for --frontmatter
  164. # Filter by multiple frontmatter fields (AND)
  165. ohs "notes" --frontmatter status:todo --frontmatter priority:high
  166. # Exclude by frontmatter value
  167. ohs "notes" --frontmatter -status:done
  168. # Filter-only mode: no query, just filters (returns all matching notes sorted by title)
  169. ohs --frontmatter status:todo
  170. ohs --folder notes/2024/
  171. ohs --tag pkm
  172. ohs --frontmatter status:done --tag archived
  173. # Unlimited results in filter-only mode (default limit is 10)
  174. ohs --folder notes/ --limit 0
  175. # Find semantically similar notes
  176. ohs --path notes/pkm/zettelkasten.md
  177. # Graph traversal: show notes linked to/from this note
  178. # Results show depth: -1/-2 = backlinks, 0 = source, +1/+2 = outgoing links
  179. ohs --path notes/pkm/zettelkasten.md --related
  180. ohs --path notes/pkm/zettelkasten.md --related --depth 2
  181. # Only outgoing links (what this note references)
  182. ohs --path notes/pkm/zettelkasten.md --related --direction outgoing
  183. # Only backlinks (who references this note)
  184. ohs --path notes/pkm/zettelkasten.md --related --direction backlinks
  185. # Traverse standard Markdown note links instead of Obsidian wikilinks
  186. ohs --path notes/pkm/zettelkasten.md --related --link-type markdown
  187. # Traverse both wikilinks and standard Markdown note links
  188. ohs --path notes/pkm/zettelkasten.md --related --link-type all
  189. # Longer context around each link
  190. ohs --path notes/pkm/zettelkasten.md --related --snippet-length 500
  191. # Rerank results with a cross-encoder model (improves precision, ~1-3s extra latency)
  192. # Downloads gte-multilingual-reranker-base ONNX (~341 MB) on first use, cached in ~/.cache/huggingface/
  193. ohs "zettelkasten atomic notes" --rerank
  194. # Show tags and aliases alongside results
  195. ohs "zettelkasten" --extended
  196. # JSON output (for scripting)
  197. ohs "spaced repetition" --json
  198. # Output only paths (one per line) — useful for piping into read
  199. ohs --frontmatter id:OHS-4 --only-paths
  200. ohs read ${(f)"$(ohs search --frontmatter status:todo --only-paths)"} # zsh: read all matching notes
  201. # Output absolute filesystem paths
  202. ohs "zettelkasten" --only-absolute-paths
  203. # Open results in Obsidian (each in a new tab)
  204. ohs "zettelkasten" --open
  205. # Reindex the vault
  206. ohs reindex
  207. ohs reindex --threads 4 # Limit local CPU inference to 4 threads
  208. # Force full reindex
  209. ohs reindex --force
  210. # Reindex a single file
  211. ohs reindex notes/pkm/zettelkasten.md
  212. # Retry only the notes whose chunks failed to embed
  213. ohs reindex --errors
  214. # Show indexing status
  215. ohs status
  216. # Show recent indexing activity
  217. ohs status --recent
  218. # Show chunks that failed to embed
  219. ohs status --errors
  220. # Read a note by path (outputs body content without frontmatter)
  221. ohs read notes/pkm/zettelkasten.md
  222. # Read raw file from vault (with frontmatter, like cat)
  223. ohs read notes/pkm/zettelkasten.md --raw
  224. # Read multiple notes (separator between each)
  225. ohs read notes/pkm/zettelkasten.md notes/pkm/evergreen-notes.md
  226. # Cap content length
  227. ohs read notes/pkm/zettelkasten.md --snippet-length 2000
  228. # Structured output with all metadata
  229. ohs read notes/pkm/zettelkasten.md --json
  230. ```
  231. ### Shell aliases
  232. Add to your `~/.zshrc` or `~/.bashrc` for quick access:
  233. ```bash
  234. alias ohss='ohs --mode semantic'
  235. alias ohst='ohs --mode title'
  236. alias ohsf='ohs --mode fulltext'
  237. alias ohsr='ohs read'
  238. alias ohsi='ohs reindex'
  239. alias ohsst='ohs status'
  240. ```
  241. Then reload (`source ~/.zshrc`) and use:
  242. ```bash
  243. ohs "zettelkasten" # hybrid search
  244. ohss "how to build a knowledge graph" # semantic
  245. ohst "zettelkasten" # fuzzy title (typo-tolerant)
  246. ohsf "permanent notes" # fulltext BM25
  247. ohsr "notes/pkm/zettelkasten.md" # read note by path
  248. ohsi # reindex vault
  249. ohsst # show status
  250. ohsst --recent # show recent indexing activity
  251. ohsst --errors # show chunks that failed to embed
  252. ```
  253. ### Output example
  254. Hybrid search returns a table with scores and snippets. Scores are color-coded by relevance:
  255. | Score | Color | Meaning |
  256. | --------- | ------ | ------------------- |
  257. | 0.8 – 1.0 | green | Highly relevant |
  258. | 0.5 – 0.8 | yellow | Moderately relevant |
  259. | 0.2 – 0.5 | plain | Somewhat relevant |
  260. | 0.0 – 0.2 | dim | Low relevance |
  261. ```
  262. ┌───────┬───────────────────────────────┬────────────────────────────────────────────┐
  263. │ SCORE │ PATH │ SNIPPET │
  264. ├───────┼───────────────────────────────┼────────────────────────────────────────────┤
  265. │ 0.98 │ notes/pkm/zettelkasten.md │ A note-taking method developed by Niklas │
  266. │ │ │ Luhmann. Each note contains one atomic... │
  267. ├───────┼───────────────────────────────┼────────────────────────────────────────────┤
  268. │ 0.72 │ notes/pkm/evergreen-notes.md │ Evergreen notes are written to evolve over │
  269. │ │ │ time. Unlike fleeting notes, they are... │
  270. └───────┴───────────────────────────────┴────────────────────────────────────────────┘
  271. ```
  272. With `--extended`, a TAGS/ALIASES column is added. Tags are prefixed with `#`, aliases are shown as-is:
  273. ```
  274. ┌───────┬───────────────────────────────┬──────────────────┬──────────────────────────────┐
  275. │ SCORE │ PATH │ TAGS/ALIASES │ SNIPPET │
  276. ├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
  277. │ 0.98 │ notes/pkm/zettelkasten.md │ #pkm │ A note-taking method... │
  278. │ │ │ ЗК │ │
  279. │ │ │ slip-box │ │
  280. ├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
  281. │ 0.72 │ notes/pkm/evergreen-notes.md │ #pkm │ Evergreen notes are written │
  282. │ │ │ #writing │ to evolve over time... │
  283. └───────┴───────────────────────────────┴──────────────────┴──────────────────────────────┘
  284. ```
  285. Title mode omits the snippet column automatically.
  286. ## MCP server
  287. Most AI assistants operate without access to your personal knowledge and can only work with what you paste into the conversation. Adding this server gives any MCP-compatible assistant a persistent, searchable index of your entire vault. It becomes a tool call, not a copy-paste session: the assistant queries your notes the same way it calls any other tool, gets ranked results with snippets and links, and can navigate your knowledge graph on request.
  288. Add to your MCP config (`.mcp.json`, `claude_desktop_config.json`, or equivalent for your client).
  289. ### Minimal config (local embeddings, no API key)
  290. Uses the built-in `Xenova/multilingual-e5-small` model. It works fully offline and supports 100+ languages. Downloads ~117 MB on first run.
  291. ```json
  292. {
  293. "mcpServers": {
  294. "obsidian-hybrid-search": {
  295. "command": "npx",
  296. "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
  297. "env": {
  298. "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
  299. }
  300. }
  301. }
  302. }
  303. ```
  304. ### Full config (OpenRouter)
  305. ```json
  306. {
  307. "mcpServers": {
  308. "obsidian-hybrid-search": {
  309. "command": "npx",
  310. "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
  311. "env": {
  312. "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
  313. "OBSIDIAN_PREFIX": "myvault_",
  314. "OBSIDIAN_RESPECT_GITIGNORE": "true",
  315. "OBSIDIAN_IGNORE_PATTERNS": ".obsidian/**,templates/**,*.canvas",
  316. "OBSIDIAN_INCLUDE_PATTERNS": "private/notes/**",
  317. "OPENAI_API_KEY": "sk-or-v1-...",
  318. "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
  319. "OPENAI_EMBEDDING_MODEL": "openai/text-embedding-3-small"
  320. }
  321. }
  322. }
  323. }
  324. ```
  325. > **Note:** On first run, `npx` will install the package automatically. Ignore patterns are persisted in the database and restored on every subsequent startup even if the env var is missing.
  326. ### Shared HTTP server
  327. Use this when multiple MCP clients should share one long-lived search/indexing process.
  328. Start or reuse the background server:
  329. ```bash
  330. OBSIDIAN_VAULT_PATH="/path/to/your/vault" ohs serve
  331. ```
  332. `serve` starts the MCP server over HTTP by default; `serve --http` is the explicit equivalent. The command prints the server URL, PID, log path, and a client config snippet. The default bind address is `127.0.0.1:3939`.
  333. Then add this to a URL-based MCP client config (`.mcp.json`, `claude_desktop_config.json`, or equivalent):
  334. ```json
  335. {
  336. "mcpServers": {
  337. "obsidian-hybrid-search": {
  338. "url": "http://127.0.0.1:3939/mcp"
  339. }
  340. }
  341. }
  342. ```
  343. Manage the server:
  344. ```bash
  345. ohs serve status
  346. ohs serve stop
  347. ohs serve --foreground
  348. ohs serve --http --foreground
  349. ```
  350. HTTP mode uses stateless MCP Streamable HTTP. It does not issue or validate `Mcp-Session-Id`, so an MCP client can continue making tool calls after the daemon restarts even if it still sends a stale session header. This mode is intended for the server's request/response tools and does not provide persistent SSE streams, server-initiated notifications, or SSE resume.
  351. If port 3939 is already in use, the command exits with an error instead of choosing another port automatically. Use `--port` for separate vaults.
  352. When binding beyond localhost, allow every hostname or address that MCP clients will use.
  353. ```bash
  354. ohs serve \
  355. --host 0.0.0.0 \
  356. --allowed-host 192.168.1.20:3939 \
  357. --allowed-host notes.example.com:3939
  358. ```
  359. Repeat `--allowed-host` for multiple values. You can also set a comma-separated list with `OBSIDIAN_MCP_ALLOWED_HOSTS`. The `--allow-any-host` option disables Host-header protection for trusted networks.
  360. ### Available MCP tools
  361. | Tool | Description |
  362. | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  363. | `search` | Search the vault. Use `query` for text search (`mode`: hybrid/semantic/fulltext/title) or `path` for semantic similarity. Combine `path` with `related: true` for graph traversal. Pass `queries[]` for multi-query fan-out (parallel search, RRF merge). Supports `scope`, `tag`, `limit`, `threshold`, `depth`, `direction`, `snippet_length`, `rerank` |
  364. | `read` | Fetch one or more notes by vault-relative path. Returns full content, title, aliases, tags, links, and backlinks. On path miss: returns `found: false` with top-3 fuzzy suggestions. Accepts a single path or an array. Use `snippet_length` to cap content size |
  365. | `reindex` | Reindex the vault or a specific file |
  366. | `status` | Show total notes, indexed count, last indexed time |
  367. Set `OBSIDIAN_PREFIX` to add a prefix to every tool name. For example, `myvault_` produces `myvault_search` and `myvault_read`. The prefix is empty by default.
  368. ## Configuration
  369. | Environment variable | Default | Description |
  370. | ---------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  371. | `OBSIDIAN_VAULT_PATH` | Required for MCP; CLI auto-detects | Absolute path to your vault |
  372. | `OBSIDIAN_PREFIX` | `""` | Optional MCP tool prefix, e.g. `myvault_` → `myvault_search`, `myvault_read` |
  373. | `OBSIDIAN_IGNORE_PATTERNS` | `.obsidian/**,templates/**,*.canvas` | Comma-separated ignore patterns |
  374. | `OBSIDIAN_RESPECT_GITIGNORE` | `true` | Read root and nested `.gitignore` files; set to `false` to disable |
  375. | `OBSIDIAN_INCLUDE_PATTERNS` | `""` | Comma-separated patterns to re-include notes ignored only by `.gitignore` |
  376. | `OBSIDIAN_CONTENT_IGNORE_PATTERNS` | `""` | Comma-separated regex rules for note body text to leave out of search, e.g. `/%%[\s\S]*?%%/g`. Original files and `read` stay unchanged. |
  377. | `OBSIDIAN_CHUNK_TOKENS` | `512` for new indexes | Chunk size in estimated tokens: a positive integer capped by the model's context limit. Stored per index; changes require a full `reindex --force`. When unset, the saved size is retained. |
  378. | `OPENAI_API_KEY` | None | API key; omit to use local model embeddings or keyless servers (Ollama, LM Studio) |
  379. | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | API base URL |
  380. | `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model name |
  381. ### Ignore patterns
  382. - Use `folder/**` to ignore a directory and all its contents.
  383. - Use `*.canvas` to ignore files by extension.
  384. - Use `exact/path.md` to ignore a specific file.
  385. - Use `**/node_modules/**` to ignore a directory at any depth.
  386. Root and nested `.gitignore` files are respected by default. Set `OBSIDIAN_RESPECT_GITIGNORE=false` to disable this behavior. Use `OBSIDIAN_INCLUDE_PATTERNS` to re-include Markdown notes that are ignored only by `.gitignore`. Include patterns do not override `OBSIDIAN_IGNORE_PATTERNS` or internal exclusions.
  387. The database stores the ignore configuration and restores it when the server restarts, even if the environment variable is missing.
  388. ## How it works
  389. 1. **Indexing** splits notes by headings with a sliding-window fallback, creates embeddings, and stores the results in SQLite with FTS5 and `sqlite-vec`.
  390. 2. **Search** runs BM25, fuzzy trigram title and alias search, and vector KNN search in parallel. BM25 uses weights of 10× for titles, 5× for aliases, and 1× for content. RRF then gives semantic and BM25 results a weight of 1.5× each, exact alias matches 2×, and partial fuzzy matches 0.25×. The final scores range from 0 to 1, where higher scores mean greater relevance.
  391. 3. **Links** are resolved from wikilinks such as `[[note]]`, mapped to note paths, and stored. Every search result includes `links` and `backlinks` arrays.
  392. 4. **Watcher** uses `chokidar` to detect file changes and update the index in the background.
  393. ## License
  394. MIT
  395. [obsidian-plugin]: https://community.obsidian.md/plugins/hybrid-search

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.