enquire-mcp

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 · AGENTS.md · API.

The most advanced Obsidian MCP. Long-term memory for AI agents.

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.

⚡ 30-second install · 🧠 Use cases · 📊 Benchmarks · 📖 API reference · 💬 Compare alternatives

The problem

Every 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, ChatGPT Memory, Cursor memory) lock your knowledge into one provider's cloud — and forget it again when you switch tools. Your knowledge keeps starting over.

The solution

Your 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.

Three things make enquire-mcp different:

1. Vendor-neutral. Your memory lives in .md files. Switch from Claude to Cursor — your memory comes with you.

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.

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.

44 tools · 19 MCP prompts · 923 unit tests · 50+ languages · v3.8.x stable · semver-bound · MIT · SLSA-3 signed.

⚡ Quick start

npm install -g @oomkapwn/enquire-mcp
enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

Drop into any MCP client:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@oomkapwn/enquire-mcp", "serve", "--vault", "/path/to/vault"]
    }
  }
}

📂 Drop-in configs in examples/ — Claude Desktop, Cursor, ChatGPT custom GPT (remote MCP over HTTP), plus a sample query set for the eval harness.

Want full hybrid power? One-command zero-touch onboarding:

enquire-mcp setup --vault <path>     # downloads model, builds FTS5 + embed-db
enquire-mcp serve --vault <path> --persistent-index --enable-reranker --use-hnsw
enquire-mcp doctor --vault <path>    # color-coded ✓/⚠/✗ health check

🤖 Set up in your AI agent — copy-paste prompts

Once enquire-mcp is installed, paste these prompts into your agent so it knows the vault is available as memory.

# Add the MCP server to your Claude Code config (one time)
claude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

Then in any Claude Code session:

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.

Drop examples/claude-desktop-hybrid.json into Claude Desktop's MCP config (edit the vault path first). Restart Claude Desktop, then:

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.

Drop examples/cursor-mcp.json at ~/.cursor/mcp.json (edit the vault path). In your .cursorrules file or chat:

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.

Follow examples/chatgpt-actions.md to expose serve-http via a tunnel with bearer auth. In your custom GPT's instructions:

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.

Same npx -y @oomkapwn/enquire-mcp serve --vault <path> 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.

Example queries that work well

• "Find every note where I discussed pricing strategy, summarize the evolution." — RRF fusion + reranker handles "evolution" semantically

• "What was my decision on PostgreSQL vs MongoDB? Cite the daily note." — wikilink graph-boost surfaces the central decision doc

• "Анализируй мои заметки о RAG за последние 3 месяца" — multilingual embeddings + frontmatter date filter

• "What pages of the LLaMA-3 paper PDF talk about scaling?" — PDFs blended into search with [page: N] citations

• "Show me topical communities in my research vault — what themes have I been exploring?" — obsidian_get_communities (GraphRAG-light)

🧠 Use cases

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.

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.

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.

📖 API reference

Auto-generated API reference at 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 (TypeDoc → GitHub Pages). Drift-free by construction: the same TSDoc that AI agents and IDEs see is what's published.

🏆 Why it's the best

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:

Comparison 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 docs/benchmarks.md — measured rerank-bge delta is +24.7 MRR / +15.5 NDCG@10 over plain hybrid on a 60-query ablation.

Strategic claim: enquire-mcp is the open-source backend for Karpathy-style LLM Wikis on top of your existing Obsidian vault. Knowledge that compounds, traceable to sources.

🏗️ How retrieval works

graph LR
    Q[Query] --> S[obsidian_search]
    S --> BM25[BM25 / FTS5]
    S --> TFIDF[TF-IDF cosine]
    S --> EMB[ML embeddings<br/>HNSW]
    BM25 --> RRF{RRF fusion<br/>k=60}
    TFIDF --> RRF
    EMB --> RRF
    RRF --> GB[Graph boost<br/>α × in-degree]
    GB --> RR[BGE cross-encoder<br/>reranker]
    RR --> R[Ranked hits<br/>per_signal observability]

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 +5-10 NDCG@10. Every hit returns per_signal: { bm25, tfidf, embeddings } so you see WHY it ranked.

🛠️ All 44 tools

The umbrella obsidian_search plus 43 specialized tools (33 always-on read + 4 opt-in + 7 gated writes). Full reference: docs/api.md.

Plus 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.

🛡️ Trust

Full posture: SECURITY.md · Stability surface: STABILITY.md · Vulns: oomkapwn@gmail.com.

❓ FAQ

Need Obsidian installed? No. Reads .md + .canvas + .pdf directly. Works against any Obsidian-format vault.

Will it write to my vault? Not unless you pass --enable-write. All 7 write tools are gated; destructive ones support dry_run.

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.

Performance? Cold-build FTS5: ~5s/1k notes, ~30s/50k. BM25 query: <100ms always. Embedding build: ~30ms/chunk on M1. HNSW top-10: sub-10ms at any scale. Serve cold-start: ~50ms with HNSW persistence.

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.

Run remotely? Yes — serve-http exposes the same server over 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.

🚀 Releases

v3.0.0 — stable channel. The v2.x retrieval roadmap is complete and the public surface is now semver-bound. Highlight reel:

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 (on @rc): OCR'd PDF watcher embed-sync, HNSW in-memory live update on file changes, R-10 adaptive HNSW refill (closes the >66% excluded under-return).

Channel: npm install @oomkapwn/enquire-mcp → latest stable (@latest = v3.8.x). Pre-release: npm install @oomkapwn/enquire-mcp@rc (currently v3.9.0-rc.3). Full changelog: CHANGELOG.md.

🤝 Contributing

git clone https://github.com/oomkapwn/enquire-mcp.git
cd enquire-mcp && npm install
npm test       # full suite (923 tests, ~5s)
npm run lint   # zero warnings
npm run build  # tsc → dist/

Issues, PRs, ideas welcome. Branch protection requires PR review on main.

📜 License

MIT. Built by Alex (@OomkaBear). Named after Tim Berners-Lee's 1980 prototype of the WWW — the original hypertext system, before the web. The original spec was: you could ask the system anything. enquire-mcp brings that to your vault.