claude mcp add obsidian -- npx -y @oomkapwn/enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

Your AI is brilliant. Its memory is fragmented.

Every new chat drops project history, decisions, research, and hard-won context. Vendor memory helps inside one product, then disappears when you move to another agent. Traditional file connectors can open a note when the path is already known; vector search can find a similar paragraph; neither is a complete memory system.

enquire-mcp turns Obsidian into the memory database for your agents

One install turns your existing vault into a persistent, queryable knowledge database for any MCP-compatible agent. It indexes locally, retrieves across formats, ranks by lexical + semantic + graph evidence, and returns the source context an agent can cite. The original files remain readable and editable without enquire-mcp.

Memory you own. Most conversation-memory products extract facts from chats into a separate store. enquire-mcp starts from the knowledge you deliberately kept: Markdown, frontmatter, wikilinks, PDFs, Canvas, and Bases. Recall is grounded in source material rather than a hidden paraphrase.

Document intelligence without a data migration. PDFs enter the same local search path as notes and return page citations. OCR can recover scanned pages. Canvas becomes a typed graph. Bases becomes an executable query surface instead of an opaque attachment.

Freshness, not timeless recall. Every search hit can carry age_days and stale; optional recency weighting helps agents prefer newer knowledge and re-check old facts instead of confidently repeating them.

What makes enquire-mcp different:

1. Vendor-neutral. Your memory lives in .md files. Switch from Claude to Cursor — your memory comes with you.
2. Full-stack local retrieval. Hybrid BM25 + TF-IDF + multilingual embeddings fused via RRF, with an optional BGE cross-encoder reranker and per-signal scores; HNSW + int8 quantization scale the dense path.
3. Zero cloud calls during serve. The embedding model runs on your machine and indexes the markdown you wrote — that's why it's a one-time local download (~110 MB), not a cloud API key. Grounded + private isn't free, and we don't pretend it is: your vault content never leaves your machine, air-gap-safe by default (enforced, not aspirational).
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.

46 tools · 19 MCP prompts · 1720 unit tests · 50+ languages · v3.11.x stable · semver-bound · MIT · npm build provenance (SLSA L2).

🏆 Why enquire-mcp is the complete Obsidian intelligence stack

Most alternatives solve one layer: an in-app similarity panel, a capable search engine, or MCP file access. enquire-mcp combines the full local retrieval ladder, agent orchestration, rich-document coverage, freshness, safety, and release discipline in one package.

_{✅ = the complete row is built in. ✕ = the complete combination was not documented on the reviewed public product surface; a project may implement part of the row or add it later. Review date: 2026-07-25. Exact source snapshots and row-by-row boundaries: competitive evidence.}

That is the TOP-1 thesis: one source of truth, one local intelligence layer, every agent — without reducing your knowledge to a cloud memory blob.

enquire-mcp is the open-source backend for Karpathy-style LLM Wikis on top of the Obsidian vault you already own: knowledge that compounds, with every answer traceable to source.

⚡ 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"]
    }
  }
}

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

Don't want to hand-assemble config? Let the CLI print the exact snippet for your vault + client (non-destructive — it writes nothing). Since v3.11.6:

enquire-mcp configure --vault <path>                 # prints config for every client
enquire-mcp configure --vault <path> --client cursor # just one (claude-code|cursor|vscode|codex|windsurf|claude-desktop|http)

The output is honest about each client's install boundary: VS Code gets its official review-and-install URI, Claude Code and Codex get copy-and-run commands, and clients whose one-click flow only accepts Marketplace/Registry entries are labeled copy-only with the exact fallback config. The generated vault path and physical package entrypoint remain visible for review before anything is saved.

Want full hybrid power? Complete the hybrid preflight, then serve:

npm install -g @oomkapwn/enquire-mcp@3.12.0-rc.17      # exact prerelease package
enquire-mcp --version
# recommended: preview first, then explicitly apply the same package-coherent plan
enquire-mcp first-run --tier hybrid --client claude-desktop --vault <path>
enquire-mcp first-run --tier hybrid --client claude-desktop --vault <path> --apply
# manual equivalent below: choose this instead of first-run --apply, not in addition
enquire-mcp setup --vault <path>                          # caches embedder; builds FTS5 + embed-db
enquire-mcp install-model rerank-bge                      # caches the offline reranker
enquire-mcp doctor --tier hybrid --vault <path>           # structural/runtime readiness
enquire-mcp configure --tier hybrid --client claude-desktop --vault <path>
enquire-mcp serve --vault <path> --persistent-index --enable-reranker --use-hnsw

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

Every connection now receives configuration-aware initialize.instructions: the recommended recall workflow, citation and freshness semantics, active write posture, and the rule that retrieved vault content is data rather than instructions. Clients that surface MCP server instructions can use that contract automatically. The copy-paste prompts below remain useful as an explicit user preference or for hosts that do not expose server instructions.

# 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

enquire-mcp configure --client vscode --vault <path>

enquire-mcp configure --client codex --vault <path>

Reusable agent rule (drop into any AGENTS.md / CLAUDE.md / .cursorrules so the agent knows when to reach for the vault):

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.

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. Your knowledge isn't locked into one vendor's memory layer; 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.

✅ Built for serious local knowledge workflows

Choose enquire-mcp when you want:

• Your Obsidian vault to remain the source of truth instead of copying knowledge into another proprietary store.
• One memory layer across many AI agents so switching models never means starting over.
• Conceptual and multilingual recall that survives different wording, not only exact string matches.
• Cited, inspectable answers with note paths, PDF pages, signal scores, and freshness metadata.
• Local-first privacy with read-only defaults, explicit write gates, and zero cloud calls during serve.
• A complete retrieval backend spanning hybrid search, reranking, graph context, agentic expansion, rich Obsidian formats, and remote MCP.

Clear scope: enquire-mcp is a headless MCP server / CLI for Markdown, Canvas, Bases, and PDF knowledge. Use exact-search tools alongside it for literal tokens; use the built-in HTTP transport when agents need remote access.

📖 Product site & API reference

The product front door explains the cited-memory outcome, proof, client paths, and AI-readable resources. The complete auto-generated API reference documents every tool, prompt, and exported helper with full TSDoc (@param / @returns / @example). Both are rebuilt from source on every push to main via publish-docs.yml; historical deep TypeDoc URLs remain valid.

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

🛠️ All 46 tools

46 production tools total: 34 always-on read tools (incl. the umbrella obsidian_search) + 4 opt-in read + 7 gated writes + 1 closed-loop feedback. 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? Outbound downloads occur only on explicit acquisition commands: enquire-mcp setup, enquire-mcp build-embeddings, and enquire-mcp install-model may fetch ONNX weights from HuggingFace; enquire-mcp install-ocr-lang fetches a Tesseract language pack. Serve mode never makes outbound HTTP (enforced, not aspirational). Embeddings + reranker run on CPU locally.

Performance? It depends on vault size, hardware, model, and enabled retrieval layers. The public evidence includes a production report of 50–100ms BM25 top-10 at 1,771 chunks / 368 files plus a reproducible synthetic benchmark showing 37–103× FTS5 speedup over linear scan at 100–1,000 notes. Run the built-in eval and benchmark commands on your vault before setting a latency SLO; see benchmarks and the FTS5 implementation note.

Languages? The default embedder is paraphrase-multilingual-MiniLM-L12-v2 (50+ languages), validated end-to-end on Russian + English bilingual vaults. The default cross-encoder reranker is rerank-bge (English-only; the only catalog alias verified end-to-end); multilingual reranker aliases currently fail their transformers.js tokenizer compatibility check. CJK/Thai/Khmer tokenization uses 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 stable: 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). · v3.10 stable: forgetting-aware freshness — age_days + stale flag + opt-in --recency-weight re-ranking + frontmatter-aware obsidian_search.

Channel: npm install @oomkapwn/enquire-mcp → latest stable (@latest = v3.11.x). Pre-release: npm install @oomkapwn/enquire-mcp@rc (the latest release candidate — see CHANGELOG.md). Full changelog: CHANGELOG.md · Forward plan: ROADMAP.md.

🤝 Contributing

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

Issues, PRs, ideas welcome. For setup questions, bug reports, and private security routing, see SUPPORT.md.

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