enquire-mcp API reference - v4.0.0-rc.7
    Preparing search index...

    Function embeddingsSearch

    • ML embeddings retrieval — k-NN over a persistent vector index.

      Hits a .embed.db (SQLite) built by enquire-mcp build-embeddings. The index is opt-in and out-of-band: this function lazy-loads the @huggingface/transformers runtime + the embedder model only when called. If the user hasn't run build-embeddings, returns a clean error pointing to the setup command instead of blocking inside model load.

      Supports HyDE (Hypothetical Document Embeddings, Gao et al 2023): pass hypothetical_answer and that text is embedded instead of query — typically +2-5 NDCG@10 on under-specified queries. Optional HNSW approximate nearest-neighbor acceleration is used when an HnswSearchContext is provided; otherwise falls back to brute-force cosine in EmbedDb.

      Privacy contract: hits are filtered through vault.isExcluded() before return — entries in the .embed.db for paths now matched by --exclude-glob / --read-paths never leak through. To keep the returned count stable under normal exclude-glob use, the search over-fetches by 2× (brute-force) or 6× (HNSW). Under extreme configurations where the majority of the embed-db is excluded, fewer than limit results may be returned — this is accepted behavior: privacy takes precedence over result count.

      Parameters

      • vault: Vault

        The vault. Used for path-exclusion filtering and to error on missing index with a guidance message.

      • args: {
            folder?: string;
            hypothetical_answer?: string;
            limit?: number;
            min_score?: number;
            model?: string;
            query: string;
        }

        query is required + non-empty. limit defaults to 10, min_score to 0.3 (relatively high cosine floor — embeddings cosine has a tighter distribution than TF-IDF). model overrides the embedder alias. hypothetical_answer enables HyDE.

        • Optionalfolder?: string
        • Optionalhypothetical_answer?: string

          v3.1.0 — HyDE (Hypothetical Document Embeddings) augmentation. When set, this string is embedded instead of query. The agent generates a synthetic answer to its own question, embeds that, and retrieves against the answer-shaped vector — typically beats raw-query retrieval on under-specified queries by +2-5 NDCG@10. The query string is still echoed in the response for caller audit-trail; it does NOT influence retrieval when hypothetical_answer is present.

        • Optionallimit?: number
        • Optionalmin_score?: number
        • Optionalmodel?: string
        • query: string
      • embedFile: string | null

        Absolute path to the .embed.db, or null when this prepared server generation froze embeddings as unavailable. Existence is checked before any model load so the error message is fast and clear.

      • Optionalhnsw: HnswSearchContext | null

        Optional HNSW index context. When passed, k-NN routes through HNSW instead of brute-force cosine.

      • OptionalwatcherHealth: Readonly<{ semanticUsable: boolean }> | null

        Optional semantic-route health for this prepared server generation. A quarantined semantic route rejects instead of returning a stale post-failure index.

      Returns Promise<EmbedSearchResponse>

      An EmbedSearchResponse with chunk-level matches and a hyde: true marker iff HyDE actually fired.

      If a non-null embedFile does not end exactly in .embed.db; admission runs before vault or index filesystem I/O.

      If query is empty, the embed db doesn't exist, the embedder fails to load, or returns no vectors for the query.

      const result = await embeddingsSearch(
        vault,
        {
          query: "How do BM25 and embeddings compare on multilingual recall?",
          limit: 10,
          hypothetical_answer: "BM25 dominates on rare-term Latin queries..."
        },
        "/path/to/vault.embed.db"
      );
      console.log(result.matches[0]?.path, result.hyde); // true

    Settings
    Member Visibility