@wei840222/qmd 2026.8.23 → 2026.8.28

package/dist/db.js

@@ -1,57 +1,11 @@
 /**
- * db.ts - Cross-runtime SQLite compatibility layer
+ * db.ts - SQLite database connection and extension management
  *
- * Provides a unified Database export that works under both Bun (bun:sqlite)
- * and Node.js (better-sqlite3). The APIs are nearly identical — the main
- * difference is the import path.
- *
- * On macOS, Apple's system SQLite is compiled with SQLITE_OMIT_LOAD_EXTENSION,
- * which prevents loading native extensions like sqlite-vec. When running under
- * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
- * SQLite build before creating any database instances.
+ * Provides Database export and connection management using better-sqlite3
+ * and sqlite-vec.
  */
-export const isBun = "Bun" in globalThis;
-let _Database;
-let _sqliteVecLoad;
-if (isBun) {
-    // Dynamic string prevents tsc from resolving bun:sqlite on Node.js builds
-    const bunSqlite = "bun:" + "sqlite";
-    const BunDatabase = (await import(/* @vite-ignore */ bunSqlite)).Database;
-    // See: https://bun.com/docs/runtime/sqlite#setcustomsqlite
-    if (process.platform === "darwin") {
-        const homebrewPaths = [
-            "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib", // Apple Silicon
-            "/usr/local/opt/sqlite/lib/libsqlite3.dylib", // Intel
-        ];
-        for (const p of homebrewPaths) {
-            try {
-                BunDatabase.setCustomSQLite(p);
-                break;
-            }
-            catch { }
-        }
-    }
-    _Database = BunDatabase;
-    // setCustomSQLite may have silently failed — test that extensions actually work.
-    try {
-        const { getLoadablePath } = await import("sqlite-vec");
-        const vecPath = getLoadablePath();
-        const testDb = new BunDatabase(":memory:");
-        testDb.loadExtension(vecPath);
-        testDb.close();
-        _sqliteVecLoad = (db) => db.loadExtension(vecPath);
-    }
-    catch {
-        // Vector search won't work, but BM25 and other operations are unaffected.
-        _sqliteVecLoad = null;
-    }
-}
-else {
-    // Dual-runtime: better-sqlite3 matches Database at runtime; published types do not share an interface with bun:sqlite.
-    _Database = (await import("better-sqlite3")).default;
-    const sqliteVec = await import("sqlite-vec");
-    _sqliteVecLoad = (db) => sqliteVec.load(db);
-}
+import BetterSqlite3 from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
 function isBusyError(err) {
     if (typeof err !== "object" || err === null)
         return false;
@@ -86,14 +40,12 @@ function enableWal(db, budgetMs) {
     }
 }
 /**
- * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ * Open a SQLite database using better-sqlite3.
  *
- * `bun:sqlite` and `better-sqlite3` both default `busy_timeout` to 0, so
- * concurrent writers throw `SQLITE_BUSY` instead of waiting. WAL improves
- * read-while-write concurrency but does not serialise writers. Setting the
- * timeout at connection open makes parallel processes (e.g. an `update` or
- * `query` racing a long `embed`, or a first-open schema migration racing any
- * routine command) queue at batch boundaries instead of failing on contact.
+ * `better-sqlite3` defaults `busy_timeout` to 0, so concurrent writers throw
+ * `SQLITE_BUSY` instead of waiting. WAL improves read-while-write concurrency
+ * but does not serialise writers. Setting the timeout at connection open makes
+ * parallel processes queue at batch boundaries instead of failing on contact.
  *
  * WAL is enabled here too (with a bounded retry) so connection-level pragmas
  * live in one place and the cold-database journal migration survives concurrent
@@ -101,11 +53,10 @@ function enableWal(db, budgetMs) {
  *
  * Default 120_000 ms outlasts the worst-case batch commit on a multi-GB
  * index. Override with `QMD_SQLITE_BUSY_TIMEOUT` (value in milliseconds; `0`
- * restores the upstream fail-fast behaviour). See
- * https://bun.sh/docs/api/sqlite#busy-timeout.
+ * restores the upstream fail-fast behaviour).
  */
 export function openDatabase(path) {
-    const db = new _Database(path);
+    const db = new BetterSqlite3(path);
     const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
     const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
     const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
@@ -115,10 +66,8 @@ export function openDatabase(path) {
 }
 /** Open an existing database without changing journal mode, schema, or user data. */
 export function openReadOnlyDatabase(path) {
-    const options = isBun
-        ? { readonly: true, create: false }
-        : { readonly: true, fileMustExist: true };
-    const db = new _Database(path, options);
+    const options = { readonly: true, fileMustExist: true };
+    const db = new BetterSqlite3(path, options);
     const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
     const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
     const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
@@ -128,16 +77,14 @@ export function openReadOnlyDatabase(path) {
 /**
  * Load the sqlite-vec extension into a database.
  *
- * Throws with platform-specific fix instructions when the extension is
- * unavailable.
+ * Throws with fix instructions when the extension is unavailable.
  */
 export function loadSqliteVec(db) {
-    if (!_sqliteVecLoad) {
-        const hint = isBun && process.platform === "darwin"
-            ? "On macOS with Bun, install Homebrew SQLite: brew install sqlite\n" +
-                "Or install qmd with npm instead: npm install -g @wei840222/qmd"
-            : "Ensure the sqlite-vec native module is installed correctly.";
-        throw new Error(`sqlite-vec extension is unavailable. ${hint}`);
+    try {
+        sqliteVec.load(db);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`sqlite-vec extension is unavailable. Ensure the sqlite-vec native module is installed correctly: ${message}`);
     }
-    _sqliteVecLoad(db);
 }

package/dist/hybrid-llm.d.ts

@@ -12,6 +12,7 @@ export declare class HybridLLM implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     dispose(): Promise<void>;

package/dist/index.d.ts

@@ -75,6 +75,8 @@ export interface SearchOptions {
     explain?: boolean;
     /** Query expansion policy (default: auto) */
     expansion?: ExpansionMode;
+    /** Whether to include HyDE (hypothetical document) in query expansion (default: true) */
+    includeHyde?: boolean;
     /** Optional progress/decision hooks for search orchestration */
     hooks?: SearchHooks;
     /** Chunk strategy: "auto" (default, uses AST for code files) or "regex" (legacy) */
@@ -100,6 +102,10 @@ export interface VectorSearchOptions {
 export interface ExpandQueryOptions {
     /** Additional context used only while generating query expansions. */
     expansionContext?: string;
+    /** Whether to include lexical (BM25) sub-queries (default: true) */
+    includeLexical?: boolean;
+    /** Whether to include HyDE (hypothetical document) sub-queries (default: true) */
+    includeHyde?: boolean;
 }
 /**
  * Options for creating a QMD store.

package/dist/index.js

@@ -231,6 +231,7 @@ export async function createStore(options) {
                 expansionContext: opts.expansionContext,
                 rerankContext: opts.rerankContext,
                 expansion: opts.expansion,
+                includeHyde: opts.includeHyde,
                 hooks: opts.hooks,
                 candidateLimit: opts.candidateLimit,
                 skipRerank,
@@ -242,7 +243,10 @@ export async function createStore(options) {
             const provider = internal.embeddingProvider;
             return internal.searchVec(q, provider?.model ?? internal.llm?.embedModelName ?? DEFAULT_EMBED_MODEL_URI, opts?.limit, opts?.collection);
         },
-        expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.expansionContext),
+        expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.expansionContext, {
+            includeLexical: opts?.includeLexical,
+            includeHyde: opts?.includeHyde,
+        }),
         get: async (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
         getDocumentBody: async (pathOrDocid, opts) => {
             const result = internal.findDocument(pathOrDocid, { includeBody: false });

package/dist/llm.d.ts

@@ -137,6 +137,7 @@ export interface ILLMSession {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     /** Whether this session is still valid (not released or aborted) */
@@ -236,6 +237,7 @@ export interface LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     /**
      * Rerank documents by relevance to a query
@@ -465,6 +467,7 @@ export declare class LlamaCpp implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     private static readonly RERANK_TEMPLATE_OVERHEAD;
     private static readonly RERANK_TARGET_DOCS_PER_CONTEXT;

package/dist/llm.js

@@ -1245,6 +1245,7 @@ export class LlamaCpp {
         const llama = await this.ensureLlama();
         await this.ensureGenerateModel();
         const includeLexical = options.includeLexical ?? true;
+        const includeHyde = options.includeHyde ?? true;
         const context = options.context;
         // Keep the caller-provided expansion context separate from the query. It
         // may clarify ambiguous terms, but it is untrusted data rather than an
@@ -1259,11 +1260,18 @@ export class LlamaCpp {
         let genContext;
         let sequence;
         try {
+            const allowedTypes = [];
+            if (includeLexical)
+                allowedTypes.push('"lex"');
+            allowedTypes.push('"vec"');
+            if (includeHyde)
+                allowedTypes.push('"hyde"');
+            const typeRule = allowedTypes.join(' | ');
             const grammar = await llama.createGrammar({
                 grammar: `
         root ::= line+
         line ::= type ": " content "\\n"
-        type ::= "lex" | "vec" | "hyde"
+        type ::= ${typeRule}
         content ::= [^\\n]+
       `
             });
@@ -1304,21 +1312,27 @@ export class LlamaCpp {
                 const type = line.slice(0, colonIdx).trim();
                 if (type !== 'lex' && type !== 'vec' && type !== 'hyde')
                     return null;
+                if (type === 'lex' && !includeLexical)
+                    return null;
+                if (type === 'hyde' && !includeHyde)
+                    return null;
                 const text = line.slice(colonIdx + 1).trim();
                 if (!hasQueryTerm(text))
                     return null;
                 return { type: type, text };
             }).filter((q) => q !== null);
-            // Filter out lex entries if not requested
-            const filtered = includeLexical ? queryables : queryables.filter(q => q.type !== 'lex');
+            // Filter out unwanted types if any slipped through
+            const filtered = queryables
+                .filter(q => (includeLexical || q.type !== 'lex'))
+                .filter(q => (includeHyde || q.type !== 'hyde'));
             if (filtered.length > 0)
                 return filtered;
             const fallback = [
-                { type: 'hyde', text: `Information about ${query}` },
-                { type: 'lex', text: query },
+                ...(includeHyde ? [{ type: 'hyde', text: `Information about ${query}` }] : []),
+                ...(includeLexical ? [{ type: 'lex', text: query }] : []),
                 { type: 'vec', text: query },
             ];
-            return includeLexical ? fallback : fallback.filter(q => q.type !== 'lex');
+            return fallback;
         }
         catch (error) {
             console.error("Structured query expansion failed:", error);

package/dist/mcp/server.js

@@ -255,8 +255,9 @@ Context-aware lex (C++ performance, not sports):
             rerankContext: z.string().optional().describe("Additional context used only to rerank results and select snippets/chunks."),
             rerank: z.boolean().optional().default(true).describe("Rerank results using LLM (default: true). Set to false for faster results on CPU-only machines."),
             explain: z.boolean().optional().default(false).describe("Include retrieval traces and the shared query-expansion decision or typed expansion error"),
+            includeHyde: z.boolean().optional().default(true).describe("Whether to include HyDE (hypothetical document) in query expansion (default: true)"),
         }),
-    }, track(async ({ query, searches, expansion, limit, minScore, candidateLimit, collections, expansionContext, rerankContext, rerank, explain }) => {
+    }, track(async ({ query, searches, expansion, includeHyde, limit, minScore, candidateLimit, collections, expansionContext, rerankContext, rerank, explain }) => {
         // Require exactly one of `query` (plain text with an expansion policy) or `searches` (typed sub-queries).
         if (!query && (!searches || searches.length === 0)) {
             return {
@@ -292,6 +293,7 @@ Context-aware lex (C++ performance, not sports):
                 rerankContext,
                 explain,
                 expansion: query ? expansion : undefined,
+                includeHyde,
                 hooks: explain && query ? {
                     onExpansionDecision: decision => { expansionDecision = decision; },
                     onExpansionError: event => { expansionError = event; },

package/dist/remote-llm.d.ts

@@ -38,6 +38,7 @@ export declare class RemoteLLM implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
         timeZone?: string;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions | string | (RerankOptions & {

package/dist/remote-llm.js

@@ -127,18 +127,29 @@ export class RemoteLLM {
             throw new Error("Remote expansion is not configured or circuit is broken.");
         }
         const includeLexical = options?.includeLexical !== false;
+        const includeHyde = options?.includeHyde !== false;
         const lexicalOutput = includeLexical ? "lex: keyword-focused search phrase\n" : "";
         const lexicalRule = includeLexical
             ? "- lex: preserve precise terms and add only useful synonyms or related keywords; do not write a complete question.\n"
             : "";
         const lexicalExample = includeLexical ? "lex: database connection pool timeout exhaustion\n" : "";
+        const hydeOutput = includeHyde ? "hyde: concise hypothetical answer-style passage\n" : "";
+        const hydeRule = includeHyde
+            ? "- hyde: write a concise hypothetical passage describing plausible answer content, describing general concepts without inventing specific fake facts.\n"
+            : "";
+        const hydeExample = includeHyde ? "hyde: Database connection pool timeout troubleshooting may examine pool limits, active connections, query latency, and connection handling.\n" : "";
+        const requestedBackends = [
+            includeLexical ? "lex" : null,
+            "vec",
+            includeHyde ? "hyde" : null,
+        ].filter(Boolean).join(", ");
         const systemPrompt = `<role>
 You are a specialized assistant for hybrid document-search query expansion.
 You expand search queries to enhance retrieval recall with analytical precision while preserving user intent and constraints.
 </role>
 
 <instructions>
-1. Proactively generate one high-quality variation for each requested backend (lex, vec, hyde) whenever the query has clear intent.
+1. Proactively generate one high-quality variation for each requested backend (${requestedBackends}) whenever the query has clear intent.
 2. Preserve query constraints and avoid inventing unmentioned facts.
 3. Return only the requested prefix lines.
 </instructions>
@@ -150,15 +161,13 @@ You expand search queries to enhance retrieval recall with analytical precision
 - Keep the query's primary language and script, while preserving exact identifiers, product names, API names, abbreviations, and established domain terms from the query or context.
 ${lexicalRule}- vec: state the search intent as a clear natural-language phrase or question.
 - For space-separated or keyword-list queries, synthesize the scattered terms into a coherent, natural-language phrase or question for vec.
-- hyde: write a concise hypothetical passage describing plausible answer content, describing general concepts without inventing specific fake facts.
-- For very short or identifier-only queries, retain exact terms without inventing unprovided constraints.
+${hydeRule}- For very short or identifier-only queries, retain exact terms without inventing unprovided constraints.
 </constraints>
 
 <output_format>
 Output only prefix lines. Do not include preambles, explanations, markdown, or code fences.
 ${lexicalOutput}vec: natural-language semantic search phrase or question
-hyde: concise hypothetical answer-style passage
-Generate at most one line of each listed type.
+${hydeOutput}Generate at most one line of each listed type.
 </output_format>
 
 <example>
@@ -173,8 +182,7 @@ database pool timeout
 </task>
 
 ${lexicalExample}vec: Why is the database connection pool timing out under load?
-hyde: Database connection pool timeout troubleshooting may examine pool limits, active connections, query latency, and connection handling.
-</example>`;
+${hydeExample}</example>`;
         const currentTime = getFormattedLocalTime(new Date(), options?.timeZone ?? this.timeZone);
         const additionalContext = options?.context
             ? `Additional context:\n${escapePromptXml(options.context)}`
@@ -224,7 +232,11 @@ Return only the prefix lines specified in the output format.
                 const match = /^(lex|vec|hyde)\s*:\s*(.+)$/i.exec(line.trim());
                 if (match && match[1] && match[2]) {
                     const type = match[1].toLowerCase();
-                    if ((type !== "lex" || options?.includeLexical !== false) && !seenTypes.has(type)) {
+                    if (type === "lex" && !includeLexical)
+                        continue;
+                    if (type === "hyde" && !includeHyde)
+                        continue;
+                    if (!seenTypes.has(type)) {
                         seenTypes.add(type);
                         results.push({ type, text: match[2].trim() });
                     }

package/dist/search/zh-dict.txt

@@ -46617,6 +46617,7 @@ c++ 3 nz
 來歷不明 5 Vi
 來歸 4 Vi
 來源 1909 N
+來源位置 1000000 nz
 來源國 18 N
 來源地 3 N
 來源場 4 N
@@ -53444,7 +53445,7 @@ c++ 3 nz
 停養 5 Vt
 停養區 1 N
 停餐 18 N
-停駐 45 Vi
+停駐 1000000 nz
 停駕 6 Vi
 停駛 271 Vi
 停驗 2 Vt
@@ -151253,6 +151254,7 @@ c++ 3 nz
 多鹽 1 N
 多麗 1 N
 多麼 338 ADV
+多點傳送 1000000 nz
 多黨 19 N
 多黨制 1 N
 夛 198 zg
@@ -181443,6 +181445,7 @@ c++ 3 nz
 封前朝 2 nr
 封包 1000000 nz
 封包交換 1000000 nz
+封包遺失 1000000 nz
 封华歆 2 nr
 封博望 3 nr
 封博陵 2 nr
@@ -223286,6 +223289,7 @@ c++ 3 nz
 快反 22 v
 快取 1000000 nz
 快取記憶體 1000000 nz
+快取項目 1000000 nz
 快咬 3 v
 快嘴 11 N
 快嘴利舌 3 i
@@ -327168,7 +327172,7 @@ c++ 3 nz
 比容 7 n
 比对 88 d
 比对法 3 n
-比對 811 Vt
+比對 1000000 nz
 比對市 1 N
 比對戰 1 N
 比小孔 2 nr
@@ -345178,7 +345182,7 @@ c++ 3 nz
 流离颠疐 3 i
 流离颠顿 3 i
 流移失所 3 i
-流程 780 N
+流程 1000000 nz
 流程再造 1000000 nz
 流程化 4 n
 流程图 18 n
@@ -386962,6 +386966,7 @@ c++ 3 nz
 生命觀 2 N
 生命诚可贵 3 i
 生命财产 3 l
+生命週期 1000000 nz
 生命體 10 N
 生員 3 N
 生唐 2 t
@@ -402286,7 +402291,7 @@ c++ 3 nz
 相究 1 Vt
 相空间 3 n
 相竞 16 v
-相符 220 Vi
+相符 1000000 nz
 相符合 3 nr
 相等 18 Vi
 相等于 3 l
@@ -448252,6 +448257,7 @@ c++ 3 nz
 群憤 1 Vi
 群戲 1 N
 群批 1 N
+群播 1000000 nz
 群擋球 1 N
 群攀 1 N
 群攻 1 Vt
@@ -456405,7 +456411,7 @@ c++ 3 nz
 背日 3 n
 背日性 3 n
 背旮旯儿 3 z
-背景 1419 N
+背景 1000000 nz
 背景值 15 N
 背景光 1 N
 背景噪声 10 n
@@ -501378,7 +501384,7 @@ c++ 3 nz
 註消 1 N
 註生娘娘 44 N
 註腳 10 N
-註解 58 N
+註解 1000000 nz
 註記 184 N
 註語 1 N
 註載 1 N
@@ -542725,7 +542731,7 @@ c++ 3 nz
 遮空蔽日 3 i
 遮簷 2 N
 遮簾 1 N
-遮罩 3 N
+遮罩 1000000 nz
 遮羞 14 Vi
 遮羞布 37 N
 遮羞費 18 N

package/dist/store.d.ts

@@ -132,6 +132,8 @@ export type ExpandedQuery = {
 };
 export type QueryExpansionOptions = {
     requireResult?: boolean;
+    includeLexical?: boolean;
+    includeHyde?: boolean;
 };
 export declare function homedir(): string;
 /**
@@ -313,7 +315,7 @@ export type Store = {
     searchVec: (query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[]) => Promise<SearchResult[]>;
     expandQuery: (query: string, model?: string, expansionContext?: string, options?: QueryExpansionOptions) => Promise<ExpandedQuery[]>;
     /** Drop the cached expansion for a query so the next call regenerates. */
-    invalidateExpansionCache: (query: string, expansionContext?: string) => void;
+    invalidateExpansionCache: (query: string, expansionContext?: string, options?: QueryExpansionOptions) => void;
     rerank: (query: string, documents: {
         file: string;
         text: string;
@@ -634,6 +636,8 @@ export type CacheKeyBody = {
     chunk?: string;
     file?: string;
     expansionContext?: string;
+    noHyde?: boolean;
+    noLex?: boolean;
 };
 export declare function getCacheKey(url: string, body: CacheKeyBody): string;
 export declare function getCachedResult(db: Database, cacheKey: string): string | null;
@@ -968,7 +972,10 @@ export declare function expandQuery(query: string, model: string | undefined, db
  * expansion's sub-queries all came back empty — left in place, the dud entry
  * would replay the same misses on every warm repeat of the query.
  */
-export declare function deleteExpansionCacheEntry(db: Database, query: string, model?: string, expansionContext?: string): void;
+export declare function deleteExpansionCacheEntry(db: Database, query: string, model?: string, expansionContext?: string, options?: {
+    includeLexical?: boolean;
+    includeHyde?: boolean;
+}): void;
 export declare function rerank(query: string, documents: {
     file: string;
     text: string;
@@ -1106,6 +1113,7 @@ export interface HybridQueryOptions {
     /** Additional context used for reranking and snippet/chunk selection. */
     rerankContext?: string;
     expansion?: ExpansionMode;
+    includeHyde?: boolean;
     skipRerank?: boolean;
     chunkStrategy?: ChunkStrategy;
     hooks?: SearchHooks;
@@ -1159,6 +1167,8 @@ export interface VectorSearchOptions {
     minScore?: number;
     /** Additional context used only while generating query expansions. */
     expansionContext?: string;
+    /** Whether to include HyDE (hypothetical document) in query expansion (default: true) */
+    includeHyde?: boolean;
     hooks?: Pick<SearchHooks, 'onExpand'>;
 }
 export interface VectorSearchResult {

package/dist/store.js

@@ -2690,7 +2690,7 @@ export function createStore(dbPath, options = {}) {
         searchVec: (query, model, limit, collectionFilter, session, precomputedEmbedding) => searchVec(db, query, model, limit, collectionFilter, session, precomputedEmbedding, store.embeddingProvider, store.authorizeRemoteRequest, store.llm),
         // Query expansion & reranking
         expandQuery: (query, model, expansionContext, options) => expandQuery(query, model ?? store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, db, expansionContext, store.llm, options),
-        invalidateExpansionCache: (query, expansionContext) => deleteExpansionCacheEntry(db, query, store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, expansionContext),
+        invalidateExpansionCache: (query, expansionContext, options) => deleteExpansionCacheEntry(db, query, store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, expansionContext, options),
         rerank: (query, documents, model, rerankContext) => {
             const llm = getLlm(store);
             return rerank(query, documents, model ?? store.localLlm?.rerankModelName ?? llm?.rerankModelName ?? DEFAULT_RERANK_MODEL, db, rerankContext, store.llm ?? llm);
@@ -3018,7 +3018,7 @@ export function countOrphanedVectors(db) {
  * Returns the number of orphaned embedding chunks deleted.
  */
 export function cleanupOrphanedVectors(db) {
-    // sqlite-vec may not be loaded (e.g. Bun's bun:sqlite lacks loadExtension).
+    // sqlite-vec may not be loaded if extension failed to initialize.
     // The vectors_vec virtual table can appear in sqlite_master from a prior
     // session, but querying it without the vec0 module loaded will crash (#380).
     if (!isSqliteVecAvailable()) {
@@ -4670,8 +4670,16 @@ export function insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt
 // Query expansion
 // =============================================================================
 export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expansionContext, llmOverride, options) {
+    const includeLexical = options?.includeLexical ?? true;
+    const includeHyde = options?.includeHyde ?? true;
     // Check cache first — stored as JSON preserving types
-    const cacheKey = getCacheKey("expandQuery", { query, model, ...(expansionContext && { expansionContext }) });
+    const cacheKey = getCacheKey("expandQuery", {
+        query,
+        model,
+        ...(expansionContext && { expansionContext }),
+        ...(!includeHyde && { noHyde: true }),
+        ...(!includeLexical && { noLex: true }),
+    });
     const cached = getCachedResult(db, cacheKey);
     if (cached) {
         try {
@@ -4693,7 +4701,11 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expans
     }
     const llm = llmOverride ?? getDefaultLlamaCpp();
     // Note: LlamaCpp uses hardcoded model, model parameter is ignored
-    const results = await llm.expandQuery(query, { context: expansionContext });
+    const results = await llm.expandQuery(query, {
+        context: expansionContext,
+        includeLexical,
+        includeHyde,
+    });
     // Map Queryable[] → ExpandedQuery[] (same shape, decoupled from llm.ts internals).
     // Filter out entries that duplicate the original query text.
     const expanded = results
@@ -4712,8 +4724,14 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expans
  * expansion's sub-queries all came back empty — left in place, the dud entry
  * would replay the same misses on every warm repeat of the query.
  */
-export function deleteExpansionCacheEntry(db, query, model = DEFAULT_QUERY_MODEL, expansionContext) {
-    const cacheKey = getCacheKey("expandQuery", { query, model, ...(expansionContext && { expansionContext }) });
+export function deleteExpansionCacheEntry(db, query, model = DEFAULT_QUERY_MODEL, expansionContext, options) {
+    const cacheKey = getCacheKey("expandQuery", {
+        query,
+        model,
+        ...(expansionContext && { expansionContext }),
+        ...(options?.includeHyde === false && { noHyde: true }),
+        ...(options?.includeLexical === false && { noLex: true }),
+    });
     db.prepare(`DELETE FROM llm_cache WHERE hash = ?`).run(cacheKey);
 }
 // =============================================================================
@@ -5491,6 +5509,7 @@ export async function hybridQuery(store, query, options) {
     if (hasStrongSignal)
         hooks?.onStrongSignal?.(topScore);
     // Step 2: Expand query (or skip if strong signal)
+    const includeHyde = options?.includeHyde ?? true;
     if (expansionDecision.action === "expand")
         hooks?.onExpandStart?.();
     const expandStart = Date.now();
@@ -5500,6 +5519,7 @@ export async function hybridQuery(store, query, options) {
             ? []
             : await store.expandQuery(query, undefined, expansionContext, {
                 requireResult: expansionDecision.reason === "explicit-force",
+                includeHyde,
             });
     }
     catch (error) {
@@ -5590,7 +5610,7 @@ export async function hybridQuery(store, query, options) {
         const runnable = expanded.filter(q => q.type === "lex" || hasVectors);
         const expansionContributed = rankedListMeta.some(m => m.queryType !== "original");
         if (runnable.length > 0 && !expansionContributed) {
-            store.invalidateExpansionCache(query, expansionContext);
+            store.invalidateExpansionCache(query, expansionContext, { includeHyde });
         }
     }
     // Step 4: RRF fusion — original-query FTS and vector lists get 2x weight;
@@ -5767,11 +5787,14 @@ export async function vectorSearchQuery(store, query, options) {
     const minScore = options?.minScore ?? 0.3;
     const collection = options?.collection;
     const expansionContext = options?.expansionContext;
+    const includeHyde = options?.includeHyde ?? true;
     if (!hasSearchableVectorIndex(store))
         return [];
     // Expand query — filter to vec/hyde only (lex queries target FTS, not vector)
     const expandStart = Date.now();
-    const allExpanded = await store.expandQuery(query, undefined, expansionContext);
+    const allExpanded = await store.expandQuery(query, undefined, expansionContext, {
+        includeHyde,
+    });
     const vecExpanded = allExpanded.filter(q => q.type !== 'lex');
     options?.hooks?.onExpand?.(query, vecExpanded, Date.now() - expandStart);
     const embedModel = store.embeddingProvider?.model ?? getLlm(store).embedModelName;