{"id":49578775,"url":"https://github.com/oomkapwn/enquire-mcp","last_synced_at":"2026-06-09T18:00:41.944Z","repository":{"id":355345677,"uuid":"1227411427","full_name":"oomkapwn/enquire-mcp","owner":"oomkapwn","description":"The most advanced Obsidian MCP — long-term memory for AI agents. Hybrid retrieval (BM25 + ML + BGE rerank, RRF-fused), HNSW live-update, agentic RAG (HyDE + sub-question), Obsidian Bases, PDFs+OCR. For Claude Code/Desktop, Cursor, ChatGPT, Codex, OpenClaw. MCP-native, MIT, SLSA L2.","archived":false,"fork":false,"pushed_at":"2026-06-06T16:51:44.000Z","size":8077,"stargazers_count":10,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T18:23:13.895Z","etag":null,"topics":["agent-memory","agentic-rag","ai-memory","chatgpt","claude","claude-code","claude-memory","codex","cursor","hybrid-search","llm-memory","long-term-memory","mcp-server","model-context-protocol","obsidian","obsidian-mcp","openclaw","rag","second-brain","semantic-search"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@oomkapwn/enquire-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oomkapwn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"oomkapwn"}},"created_at":"2026-05-02T16:40:51.000Z","updated_at":"2026-06-06T16:51:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oomkapwn/enquire-mcp","commit_stats":null,"previous_names":["oomkapwn/enquire-mcp"],"tags_count":206,"template":false,"template_full_name":null,"purl":"pkg:github/oomkapwn/enquire-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oomkapwn%2Fenquire-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oomkapwn%2Fenquire-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oomkapwn%2Fenquire-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oomkapwn%2Fenquire-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oomkapwn","download_url":"https://codeload.github.com/oomkapwn/enquire-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oomkapwn%2Fenquire-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34039536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agentic-rag","ai-memory","chatgpt","claude","claude-code","claude-memory","codex","cursor","hybrid-search","llm-memory","long-term-memory","mcp-server","model-context-protocol","obsidian","obsidian-mcp","openclaw","rag","second-brain","semantic-search"],"created_at":"2026-05-03T18:09:09.299Z","updated_at":"2026-06-09T18:00:41.935Z","avatar_url":"https://github.com/oomkapwn.png","language":"TypeScript","funding_links":["https://github.com/sponsors/oomkapwn"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://github.com/oomkapwn/enquire-mcp\"\u003e\u003cimg src=\"./assets/social-preview.png\" alt=\"enquire-mcp — the most advanced Obsidian MCP. Long-term memory for AI agents. Built on your Obsidian vault. Open-source, MCP-native, vendor-neutral. Hybrid retrieval, BGE reranker, HNSW, PDFs with OCR. For Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, OpenClaw.\" width=\"100%\"\u003e\u003c/a\u003e\n\n# enquire-mcp\n\n\u003csub\u003e**English** · [中文](./README.zh.md)\u003c/sub\u003e\n\n\u003csub\u003e**TL;DR for AI agents** — MCP server exposing a local Obsidian markdown vault to Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, and OpenClaw as persistent searchable memory. Hybrid retrieval (BM25 + ML embeddings + BGE reranker, RRF-fused), HNSW + int8 quantization, agentic RAG (HyDE + sub-question), GraphRAG-light, PDFs + OCR, standalone Bases. Vendor-neutral, MIT, zero cloud calls during serve. Install: `npm i -g @oomkapwn/enquire-mcp`. Docs: [llms.txt](https://github.com/oomkapwn/enquire-mcp/blob/main/llms.txt) · [AGENTS.md](https://github.com/oomkapwn/enquire-mcp/blob/main/AGENTS.md) · [API](https://oomkapwn.github.io/enquire-mcp/).\u003c/sub\u003e\n\n### The most advanced Obsidian MCP. Long-term memory for AI agents.\n\n**Stop re-explaining context to Claude, Cursor, ChatGPT, Codex, OpenClaw every session. Your Obsidian notes become shared, searchable memory across every MCP-compatible agent — your knowledge, every model, forever yours.**\n\n[![CI](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@oomkapwn/enquire-mcp.svg?label=npm\u0026color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)\n[![downloads](https://img.shields.io/npm/dm/@oomkapwn/enquire-mcp.svg?color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)\n[![tests](https://img.shields.io/badge/tests-1170%20passing-brightgreen.svg)](#trust)\n[![stable](https://img.shields.io/badge/v3.9.x-stable-brightgreen.svg)](./STABILITY.md)\n[![build provenance](https://img.shields.io/badge/build_provenance-SLSA_L2-blue.svg)](https://slsa.dev/spec/v1.0/levels#build-l2)\n[![MCP](https://img.shields.io/badge/MCP-1.29-8A2BE2.svg)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)\n\n**[⚡ 30-second install](#-quick-start) · [🧠 Use cases](#-use-cases) · [📊 Benchmarks](./docs/benchmarks.md) · [📖 API reference](https://oomkapwn.github.io/enquire-mcp/) · [💬 Compare alternatives](./docs/COMPARISON.md)**\n\n**Claude Code — one line:**\n\n```bash\nclaude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\\ Vault\n```\n\n\u003c/div\u003e\n\n---\n\n## The problem\n\nEvery AI session starts from zero. You re-explain your project, your design decisions, the conclusions of last week's research. Vendor \"memory\" features ([Claude Memory](https://www.anthropic.com/news/memory-and-tool-use), [ChatGPT Memory](https://openai.com/index/memory-and-new-controls-for-chatgpt/), Cursor memory) lock your knowledge into one provider's cloud — and forget it again when you switch tools. **Your knowledge keeps starting over.**\n\n## The solution\n\nYour Obsidian vault becomes **persistent, queryable long-term memory** for any MCP-compatible agent. One install — your knowledge is instantly accessible from Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, OpenClaw, and every other MCP client. Plain markdown files **you own**, indexed locally, searched with the full modern IR stack, recalled across every session and every model.\n\n**Grounded, not extracted.** Conversation-memory tools (mem0, Zep, Supermemory, Memobase) *extract* facts from your chat logs into a separate store you can't read. enquire-mcp is the inverse: it's **grounded in the knowledge you already wrote** — your own `.md` notes, verbatim, with citations — so recall is auditable, editable in any editor, and never a lossy summary of a chat you half-remember. (That \"extracted\" critique is specific to the chat-memory cohort — not to knowledge-graph / ETL tools like cognee, nor to personal-search peers like Khoj.)\n\n**Grounded — and freshness-aware.** Recalling a fact is half the problem; knowing whether it's still *true* is the other half. The [Memora benchmark](https://arxiv.org/abs/2604.20006) (Apr 2026) showed memory systems systematically fail at stale-fact reuse — recalling a year-old note as if it were written today. Because enquire's memory *is* your real markdown files, every search hit carries `age_days` + a `stale` flag derived from the note's live last-modified time, and you can opt into recency-weighted ranking (`--recency-weight`) so fresher notes surface first. Your knowledge, freshness-aware — not a timeless blob.\n\n\u003e **What makes enquire-mcp different**:\n\u003e 1. **Vendor-neutral.** Your memory lives in `.md` files. Switch from Claude to Cursor — your memory comes with you.\n\u003e 2. **Best-in-class retrieval.** Hybrid BM25 + multilingual embeddings + BGE cross-encoder reranker fused via RRF, scaled with HNSW + int8 quantization. The same IR stack a search startup would build — open-sourced, in one binary.\n\u003e 3. **Zero cloud calls during serve.** Models cached locally (one-time download from HuggingFace). Your vault content never leaves your machine. Air-gap-safe by default.\n\u003e 4. **Freshness-aware recall.** Every hit reports how old the note is; opt-in recency re-ranking lets an agent prefer fresh knowledge and flag stale facts for re-verification — the forgetting-aware frontier, built on the `mtime` your files already have.\n\n**45 tools · 19 MCP prompts · 1170 unit tests · 50+ languages · v3.9.x stable · semver-bound · MIT · npm build provenance (SLSA L2).**\n\n---\n\n## 🏆 Why it's the best\n\n**Six features no other Obsidian-MCP has at all** (GraphRAG-light, standalone `.base` execution, HyDE, int8 quantization, late-chunking, built-in eval harness). **Plus the entire modern IR stack** (BM25 + ML embeddings + cross-encoder reranking + HNSW) that competitors ship at most one or two of. Side-by-side:\n\n| Capability | enquire-mcp | Smart Connections | Other Obsidian-MCPs |\n|---|:---:|:---:|:---:|\n| Hybrid retrieval (BM25 + TF-IDF + ML embeddings, RRF-fused) | ✅ | ❌ | ❌ |\n| **Cross-encoder reranking** (BGE, +15.5 NDCG@10 measured) | ✅ | ❌ | ❌ |\n| **HNSW vector index** (sub-10ms top-K, persisted) | ✅ | ❌ | ❌ |\n| **int8 vector quantization** (~4× smaller embed-db) | ✅ | ❌ | ❌ |\n| **Late-chunking** context-windowed embeddings | ✅ | ❌ | ❌ |\n| **PDFs blended into hybrid search** (`[page: N]` citations) | ✅ | ❌ | ❌ |\n| **OCR for scanned PDFs** (Tesseract.js, multilingual) | ✅ | ❌ | ❌ |\n| **Wikilink graph-boost** retrieval signal | ✅ | ❌ | ❌ |\n| **Multilingual semantic search** (50+ languages, on-device) | ✅ | 💰 paid | ❌ |\n| **Built-in retrieval-quality eval harness** (NDCG, Recall, MRR, A/B matrix) | ✅ | ❌ | ❌ |\n| **Remote MCP** over HTTP + bearer auth + stateful sessions | ✅ | ❌ | partial |\n| **Per-signal observability** per hit | ✅ | ❌ | ❌ |\n| **MCP-native** (Claude · Cursor · ChatGPT · Codex · OpenClaw · any client) | ✅ | ❌ Obsidian-only | varies |\n| **Privacy filter** verified at every search + write path | ✅ | n/a | ❌ |\n| **45 production tools** (34 always-on read tools + 4 opt-in + 7 gated writes) | ✅ | n/a | varies |\n| **GraphRAG-light** (wikilink community detection via Louvain modularity) | ✅ **only here** | ❌ | ❌ |\n| **Standalone `.base` query execution** (works without Obsidian running) | ✅ **only here** | ❌ | ❌ delegates to Obsidian |\n| **HyDE retrieval** (Gao et al 2023) + sub-question decomposition | ✅ **only here** | ❌ | ❌ |\n| **1170 unit tests · 9 required + 5 advisory CI gates per PR** | ✅ | n/a | rare |\n| **Signed build provenance** (npm + Sigstore, SLSA Build L2) | ✅ | n/a | ❌ |\n| **Semver-bound public surface** ([STABILITY.md](./STABILITY.md)) | ✅ | n/a | ❌ |\n| Standalone (no Obsidian plugin needed) | ✅ | ❌ requires Obsidian | varies |\n| License | MIT, free | proprietary, paid | varies |\n\n\u003csub\u003eComparison based on each project's public capabilities as of v3.8.x stable (initial snapshot v3.7.0 / 2026-05-15; refreshed in v3.8.4). Smart Connections is a paid Obsidian plugin (not an MCP server). \"Other Obsidian-MCPs\" refers to public open-source Obsidian-MCP servers on GitHub at time of writing. Public end-to-end retrieval benchmarks for enquire-mcp are published in \u003ca href=\"./docs/benchmarks.md\"\u003e\u003ccode\u003edocs/benchmarks.md\u003c/code\u003e\u003c/a\u003e — measured `rerank-bge` delta is +24.7 MRR / +15.5 NDCG@10 over plain hybrid on a 60-query ablation.\u003c/sub\u003e\n\n\u003e Strategic claim: enquire-mcp is the open-source backend for [Karpathy-style LLM Wikis](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) on top of your existing Obsidian vault. Knowledge that compounds, traceable to sources.\n\n---\n\n## ⚡ Quick start\n\n```bash\nnpm install -g @oomkapwn/enquire-mcp\nenquire-mcp serve --vault ~/Documents/Obsidian\\ Vault\n```\n\nDrop into any MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@oomkapwn/enquire-mcp\", \"serve\", \"--vault\", \"/path/to/vault\"]\n    }\n  }\n}\n```\n\n📂 Drop-in configs in [`examples/`](./examples/) — **Claude Desktop**, **Cursor**, **ChatGPT custom GPT** (remote MCP over HTTP), plus a sample query set for the eval harness.\n\n**Want full hybrid power?** One-command zero-touch onboarding:\n\n```bash\nenquire-mcp setup --vault \u003cpath\u003e     # downloads model, builds FTS5 + embed-db\nenquire-mcp serve --vault \u003cpath\u003e --persistent-index --enable-reranker --use-hnsw\nenquire-mcp doctor --vault \u003cpath\u003e    # color-coded ✓/⚠/✗ health check\n```\n\n---\n\n## 🤖 Set up in your AI agent — copy-paste prompts\n\nOnce `enquire-mcp` is installed, paste these prompts into your agent so it knows the vault is available as memory.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code (terminal)\u003c/b\u003e — add MCP server + first prompt\u003c/summary\u003e\n\n```bash\n# Add the MCP server to your Claude Code config (one time)\nclaude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\\ Vault\n```\n\nThen in any Claude Code session:\n\n\u003e You now have `obsidian_*` tools that search and read my Obsidian vault — my long-term memory. Before answering questions about projects, decisions, people, or technical context, call `obsidian_search` with the relevant terms. Cite each fact with the source note (and `[page: N]` for PDFs). If you don't find a relevant note, say so — don't guess.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e — config file + first prompt\u003c/summary\u003e\n\nDrop [`examples/claude-desktop-hybrid.json`](./examples/claude-desktop-hybrid.json) into Claude Desktop's MCP config (edit the vault path first). Restart Claude Desktop, then:\n\n\u003e You have my Obsidian vault wired up as searchable memory via `obsidian_*` tools. Always check `obsidian_search` first when I ask about anything in my notes — meeting context, research, decisions, journal entries. Quote the source note path on every fact.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e — MCP stdio config + agent rule\u003c/summary\u003e\n\nDrop [`examples/cursor-mcp.json`](./examples/cursor-mcp.json) at `~/.cursor/mcp.json` (edit the vault path). In your `.cursorrules` file or chat:\n\n\u003e Before suggesting code that touches a topic I might have notes on (architecture decisions, API contracts, vendor evaluations), call `obsidian_search` first. Treat my Obsidian vault as authoritative context.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eChatGPT custom GPT\u003c/b\u003e — remote MCP over HTTP\u003c/summary\u003e\n\nFollow [`examples/chatgpt-actions.md`](./examples/chatgpt-actions.md) to expose `serve-http` via a tunnel with bearer auth. In your custom GPT's instructions:\n\n\u003e You have read access to my Obsidian vault via the `obsidian_*` tool family. Search before answering anything that might be in my notes; cite the source filepath on every claim.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenClaw / Codex / any other MCP client\u003c/b\u003e\u003c/summary\u003e\n\nSame `npx -y @oomkapwn/enquire-mcp serve --vault \u003cpath\u003e` command works for any MCP-compatible client. See the client's own MCP-config docs for where to drop the server entry, then use any of the prompts above.\n\n\u003c/details\u003e\n\n**Reusable agent rule** (drop into any `AGENTS.md` / `CLAUDE.md` / `.cursorrules` so the agent knows *when* to reach for the vault):\n\n\u003e When my question touches my own notes, decisions, projects, people, or research, **search my Obsidian vault first** via the `obsidian_*` tools (start with `obsidian_search`) and cite the source note on every fact. Prefer enquire for *conceptual / cross-language / \"what did I say about X\"* recall; use plain `grep` / `ripgrep` for exact literal strings. If nothing relevant comes back, say so — don't guess.\n\n### Example queries that work well\n\n- *\"Find every note where I discussed pricing strategy, summarize the evolution.\"* — RRF fusion + reranker handles \"evolution\" semantically\n- *\"What was my decision on PostgreSQL vs MongoDB? Cite the daily note.\"* — wikilink graph-boost surfaces the central decision doc\n- *\"Анализируй мои заметки о RAG за последние 3 месяца\"* — multilingual embeddings + frontmatter date filter\n- *\"What pages of the LLaMA-3 paper PDF talk about scaling?\"* — PDFs blended into search with `[page: N]` citations\n- *\"Show me topical communities in my research vault — what themes have I been exploring?\"* — `obsidian_get_communities` (GraphRAG-light)\n\n---\n\n## 🧠 Use cases\n\n**1 — Long-term memory for AI agents.** Drop your Obsidian vault into any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, OpenClaw). The agent now has durable, semantic recall over every meeting note, journal entry, research log, and decision doc you've ever written — across sessions, models, and providers. Unlike `Claude Memory` or `ChatGPT Memory`, your knowledge isn't locked into one vendor's cloud; it lives in plain markdown you own and can migrate freely.\n\n**2 — Personal knowledge base / second brain.** Hybrid retrieval surfaces the right note for *any* phrasing, in any of 50+ languages. Ask in English about a Russian-language journal entry from 2 years ago, get the right hit. Wikilink graph-boost reranks notes that sit at the centre of your knowledge graph. GraphRAG-light surfaces topical communities — discover connections you forgot you made. PDFs blend into search with `[page: N]` citations so research papers and meeting transcripts become first-class memory.\n\n**3 — Agentic RAG / context engineering.** `obsidian_search` exposes per-signal scores so the agent sees *why* each hit ranked. HyDE pre-rewrites vague queries into rich hypothetical answers before retrieval. Sub-question decomposition handles multi-hop questions (\"how did our pricing strategy evolve and what was the customer reaction?\") by breaking them into independent sub-queries, fusing results. The built-in eval harness (NDCG / Recall / MRR) lets you measure retrieval quality on your own queries instead of trusting vendor benchmarks.\n\n---\n\n## 🚫 When enquire-mcp is *not* the right tool\n\nHonest non-goals — reach for something else when:\n\n- **You want literal string / regex search.** `ripgrep` / `grep` is faster and exact for \"find this precise token\". enquire shines on *conceptual* recall — synonyms, cross-language, \"what did I say about X\". Use both: `rg` for literal, enquire for meaning.\n- **Your knowledge lives in chat logs, not notes.** enquire is *grounded* in the markdown you authored. Conversation-memory tools (mem0, Zep, Supermemory) that *extract* facts from chat transcripts into a separate store are a different category — see the [comparison](./docs/COMPARISON.md).\n- **You need multi-user / hosted / synced search.** enquire is local-first and single-vault by design — no server-side multi-tenant index.\n- **Your sources aren't Markdown or PDF.** `.md` / `.canvas` / `.base` / `.pdf` are first-class; other formats need conversion first.\n- **You want a GUI or an in-app Obsidian plugin.** enquire is a headless MCP server / CLI — it *complements* Obsidian, it isn't one. (Smart Connections is the in-app plugin option.)\n- **You need sub-millisecond search over millions of notes.** HNSW gives sub-10ms top-K at large scale, but enquire targets personal / team vaults, not web-scale corpora.\n\n---\n\n## 📖 API reference\n\nAuto-generated **[API reference at oomkapwn.github.io/enquire-mcp](https://oomkapwn.github.io/enquire-mcp/)** — every tool, prompt, and exported helper with full TSDoc (`@param` / `@returns` / `@example`). Rebuilt from source on every push to `main` via [`publish-docs.yml`](https://github.com/oomkapwn/enquire-mcp/blob/main/.github/workflows/publish-docs.yml) (TypeDoc → GitHub Pages). Drift-free by construction: the same TSDoc that AI agents and IDEs see is what's published.\n\n---\n\n## 🏗️ How retrieval works\n\n```mermaid\ngraph LR\n    Q[Query] --\u003e S[obsidian_search]\n    S --\u003e BM25[BM25 / FTS5]\n    S --\u003e TFIDF[TF-IDF cosine]\n    S --\u003e EMB[ML embeddings\u003cbr/\u003eHNSW]\n    BM25 --\u003e RRF{RRF fusion\u003cbr/\u003ek=60}\n    TFIDF --\u003e RRF\n    EMB --\u003e RRF\n    RRF --\u003e GB[Graph boost\u003cbr/\u003eα × in-degree]\n    GB --\u003e RR[BGE cross-encoder\u003cbr/\u003ereranker]\n    RR --\u003e R[Ranked hits\u003cbr/\u003eper_signal observability]\n```\n\n`obsidian_search` auto-detects available signals and gracefully degrades. Wikilink graph-boost reranks top-K via 1-step personalised PageRank. Optional cross-encoder reranking re-scores top-N for +15.5 NDCG@10 measured. Every hit returns `per_signal: { bm25, tfidf, embeddings }` so you see WHY it ranked.\n\n| Tier | Setup | What you get |\n|---|---|---|\n| **1** | `serve --vault \u003cpath\u003e` | TF-IDF cosine (zero setup, instant) |\n| **2** | + `--persistent-index` | + BM25 / FTS5 (sub-100ms top-10) |\n| **3** | + `setup` (downloads model + builds embed-db) | + multilingual ML embeddings |\n| **4** | + `--enable-reranker` | + BGE cross-encoder (+15.5 NDCG@10 measured) |\n| **5** | + `--use-hnsw` | + sub-10ms top-K at million-chunk scale |\n| **6** | + `--include-pdfs` | + PDFs blended into all of the above |\n| **7** | `serve-http --bearer-token …` | + remote MCP (Claude.ai web, ChatGPT, Cursor HTTP, mobile) |\n\n---\n\n## 🛠️ All 45 tools\n\nThe umbrella `obsidian_search` plus 43 specialized tools (34 always-on read + 4 opt-in + 7 gated writes). Full reference: **[docs/api.md](./docs/api.md)**.\n\n| Category | Tools |\n|---|---|\n| **Search \u0026 retrieval** | `obsidian_search` (umbrella, RRF-fused) · `obsidian_hyde_search` (HyDE-augmented, v3.1.0) · `obsidian_search_text` · `obsidian_full_text_search` · `obsidian_semantic_search` · `obsidian_embeddings_search` · `obsidian_find_similar` |\n| **Wikilinks \u0026 graph** | `obsidian_resolve_wikilink` · `obsidian_get_backlinks` · `obsidian_get_outbound_links` · `obsidian_get_note_neighbors` · `obsidian_get_unresolved_wikilinks` · `obsidian_find_path` · `obsidian_get_communities` (v3.4.0, GraphRAG-light) |\n| **Frontmatter \u0026 Dataview** | `obsidian_frontmatter_get` · `obsidian_frontmatter_search` · `obsidian_dataview_query` · `obsidian_list_tags` |\n| **Read \u0026 navigate** | `obsidian_read_note` · `obsidian_list_notes` · `obsidian_get_recent_edits` · `obsidian_stale_notes` · `obsidian_open_questions` · `obsidian_context_pack` · `obsidian_chat_thread_read` · `obsidian_open_in_ui` · `obsidian_stats` |\n| **PDFs, Canvas \u0026 Bases** | `obsidian_read_pdf` · `obsidian_list_pdfs` · `obsidian_ocr_pdf` · `obsidian_read_canvas` · `obsidian_list_canvases` · `obsidian_list_bases` (v3.2.0) · `obsidian_read_base` (v3.2.0) · `obsidian_query_base` (v3.2.0) |\n| **Writes** (gated by `--enable-write`) | `obsidian_create_note` · `obsidian_append_to_note` · `obsidian_rename_note` · `obsidian_replace_in_notes` · `obsidian_archive_note` · `obsidian_frontmatter_set` · `obsidian_chat_thread_append` |\n| **Diagnostic / lint** | `obsidian_lint_wiki` · `obsidian_paper_audit` · `obsidian_validate_note_proposal` |\n\nPlus 3 MCP resources (`obsidian://vault/info`, `obsidian://note/{path}`, `obsidian://chunk/{n}/{path}`) and 19 **MCP prompts** (`summarize_recent_edits` · `review_tag` · `find_orphans` · `weekly_review` · `extract_todos` · `process_inbox` · `consolidate_tags` · `find_duplicates` · `lint_wiki` · `monthly_review` · `search_with_query_expansion` · `vault_synth` · `vault_wiki_compile` · `vault_lint_extended` · `vault_capture` · `vault_persona_search` · `vault_automation_setup` · `vault_research` · `vault_synthesis_page`) for common vault workflows.\n\n---\n\n## 🛡️ Trust\n\n| Surface | Posture |\n|---|---|\n| **Default** | Read-only — `--enable-write` required for the 7 write tools |\n| **Least privilege** | `--disabled-tools` / `--enabled-tools` expose a minimal surface (e.g. a read-only research agent gets only `obsidian_search` + `obsidian_read_note`) |\n| **Path safety** | Realpath check on every read+write; symlinks-out-of-vault rejected |\n| **Privacy filter** | Verified at FTS5 + embed-db + chunk resource paths; fail-closed on empty allow-/deny-lists |\n| **HTTP transport** | Bearer auth (constant-time SHA-256 + `timingSafeEqual`), per-token rate-limit, strict CORS |\n| **Frontmatter** | `gray-matter` (`js-yaml` safeLoad) — no code execution |\n| **Cache + index files** | chmod 0600, parent dir 0700 |\n| **CI** | **9 required** branch-protection gates: (1) `lint`, (2) `test` on Node 22, (3) `test` on Node 24, (4) `smoke`, (5) `audit`, (6) `coverage`, (7) `version-consistency`, (8) `docs`, (9) `oia`. **5 advisory**: `test-macos` + `docker` (Dockerfile build + `tools/list` introspection smoke) via `.github/workflows/ci.yml`; CodeQL ×2 + Analyze actions via [GitHub default-setup](https://docs.github.com/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning) (not workflow files). Release workflow re-verifies all 9 required passed on tagged SHA before npm publish. _v3.7.10 — `docs` (TypeDoc generation gate) added to required set. v3.7.13 — `engines.node` floor bumped to `\u003e=22.13.0` to match the CI matrix. v3.8.0-rc.6 — `oia` (Outside-In Audit) promoted from advisory._ |\n| **Coverage** | Lines ≥86% · statements ≥82% · functions ≥75% · branches ≥74% (gated) |\n| **Releases** | npm + GitHub release per tag · semver · **signed build provenance** (npm + Sigstore, SLSA Build L2; L3 generator on the roadmap) |\n| **Stability** | v3.0+ semver-bound — every CLI flag, tool name, MCP resource, prompt, exported symbol is contract |\n\nFull posture: **[SECURITY.md](./SECURITY.md)** · Stability surface: **[STABILITY.md](./STABILITY.md)** · Vulns: `oomkapwn@gmail.com`.\n\n---\n\n## ❓ FAQ\n\n**Need Obsidian installed?** No. Reads `.md` + `.canvas` + `.pdf` directly. Works against any Obsidian-format vault.\n\n**Will it write to my vault?** Not unless you pass `--enable-write`. All 7 write tools are gated; destructive ones support `dry_run`.\n\n**Data sent anywhere?** Only on `enquire-mcp install-model` (downloads ONNX weights from HuggingFace, one-time). Serve mode never makes outbound HTTP. Embeddings + reranker run on CPU locally.\n\n**Performance?** Cold-build FTS5: ~5s/1k notes, ~30s/50k. BM25 query: \u003c100ms always. Embedding build: ~30ms/chunk on M1. **HNSW top-10: sub-10ms at any scale.** Serve cold-start: ~50ms with HNSW persistence.\n\n**Languages?** Default `paraphrase-multilingual-MiniLM-L12-v2` (50+ languages). Multilingual cross-encoder. Validated end-to-end on Russian + English bilingual vaults. CJK/Thai/Khmer tokenization via `Intl.Segmenter`.\n\n**Run remotely?** Yes — `serve-http` exposes the same server over [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http). Front with Tailscale Funnel or Cloudflare Tunnel for HTTPS. Works with claude.ai web, ChatGPT custom GPT, Cursor HTTP mode, mobile MCP clients. See **[docs/http-transport.md](./docs/http-transport.md)**.\n\n---\n\n## 🚀 Releases\n\n**v3.0.0 — stable channel.** The v2.x retrieval roadmap is complete and the public surface is now [semver-bound](./STABILITY.md). Highlight reel:\n\n`v2.0` hybrid retrieval (BM25+TF-IDF+embeddings via RRF) · `v2.6` remote MCP · `v2.7-2.8` PDFs blended · `v2.9` BGE reranker · `v2.10` OCR · `v2.11` doctor + setup · `v2.12` eval harness · `v2.13` HNSW · `v2.14` stateful sessions · `v2.15` late-chunking · `v2.16` HNSW persistence · `v2.17` int8 quantization · `v3.8.0` stable · `v3.8.7` HTTP transport hardening · **`v3.9.0` stable**: OCR'd PDF watcher embed-sync, HNSW in-memory live update on file changes, R-10 adaptive HNSW refill (closes the \u003e66% excluded under-return). · **`v3.10` (`@rc`)**: forgetting-aware freshness — `age_days` + `stale` flag + opt-in `--recency-weight` re-ranking + frontmatter-aware `obsidian_search`.\n\nChannel: `npm install @oomkapwn/enquire-mcp` → latest stable (`@latest` = v3.9.x). Pre-release: `npm install @oomkapwn/enquire-mcp@rc` (the latest release candidate — see [CHANGELOG.md](./CHANGELOG.md)). Full changelog: **[CHANGELOG.md](./CHANGELOG.md)** · Forward plan: **[ROADMAP.md](https://github.com/oomkapwn/enquire-mcp/blob/main/ROADMAP.md)**.\n\n---\n\n## 🤝 Contributing\n\n```bash\ngit clone https://github.com/oomkapwn/enquire-mcp.git\ncd enquire-mcp \u0026\u0026 npm install\nnpm test       # full suite (1170 tests, ~12s)\nnpm run lint   # zero warnings\nnpm run build  # tsc → dist/\n```\n\nIssues, PRs, ideas welcome. Branch protection requires PR review on `main`.\n\n---\n\n## 📜 License\n\nMIT. Built by [Alex (@OomkaBear)](https://github.com/oomkapwn). Named after [Tim Berners-Lee's 1980 prototype of the WWW](https://en.wikipedia.org/wiki/ENQUIRE) — the original hypertext system, before the web. The original spec was: you could ask the system anything. **enquire-mcp brings that to your vault.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foomkapwn%2Fenquire-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foomkapwn%2Fenquire-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foomkapwn%2Fenquire-mcp/lists"}