@wei840222/qmd 2026.8.24 → 2026.9.6

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+### Changed
+
+- Replace `better-sqlite3` with Node.js built-in `node:sqlite`, preventing SQLite runtime symbol collisions when QMD is embedded alongside other `node:sqlite` consumers. The minimum supported Node.js version is now 22.16.0.
+
+### Added
+
+- **Disable HyDE Expansion Control**: Added `--no-hyde` CLI option for `qmd query` and `qmd vsearch`, `includeHyde` parameter to SDK (`store.search`, `store.expandQuery`) and MCP `query` tool, allowing users to disable generating hypothetical document embeddings during query expansion.
+
 ## [2026.8.23-1] - 2026-08-23
 
 ### Added

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1e728bc",
-  "builtAt": "2026-08-23T06:13:30.733Z"
+  "commit": "672da2e",
+  "builtAt": "2026-09-06T06:45:32.394Z"
 }

package/dist/cli/qmd.js

@@ -137,12 +137,16 @@ function getStore() {
     }
     return store;
 }
-function getDoctorStore() {
+function getDoctorStore(options = {}) {
     if (!store) {
         const dbPath = getDbPath();
+        const shouldReconcile = existsSync(dbPath) && options.reconcileConfig !== undefined;
         store = existsSync(dbPath)
-            ? createStore(dbPath, { readOnly: true })
+            ? createStore(dbPath, { readOnly: !shouldReconcile })
             : createStore(":memory:");
+        if (shouldReconcile) {
+            syncConfigToDb(store.db, options.reconcileConfig);
+        }
     }
     return store;
 }
@@ -2674,6 +2678,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
             limit: opts.all ? 500 : (opts.limit || 10),
             minScore: opts.minScore || 0.3,
             expansionContext: opts.intent,
+            includeHyde: opts.includeHyde,
             hooks: {
                 onExpand: (original, expanded) => {
                     logExpansionTree(original, expanded);
@@ -2766,6 +2771,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 explain: !!opts.explain,
                 rerankContext: intent,
                 expansion: opts.expansion,
+                includeHyde: opts.includeHyde,
                 chunkStrategy: opts.chunkStrategy,
                 hooks: {
                     onExpansionDecision: (decision) => {
@@ -2884,6 +2890,7 @@ function parseCLI() {
             // Query options
             "candidate-limit": { type: "string", short: "C" },
             "no-rerank": { type: "boolean", default: false },
+            "no-hyde": { type: "boolean", default: false },
             expand: { type: "boolean", default: false },
             "no-gpu": { type: "boolean", default: false },
             intent: { type: "string" },
@@ -2960,6 +2967,7 @@ function parseCLI() {
         lineNumbers: !!values["line-numbers"],
         candidateLimit: values["candidate-limit"] ? parseInt(String(values["candidate-limit"]), 10) : undefined,
         skipRerank: !!values["no-rerank"],
+        includeHyde: !values["no-hyde"],
         explain: !!values.explain,
         intent: values.intent,
         expansion: values.expand ? "force" : "auto",
@@ -3459,6 +3467,7 @@ function showHelp() {
     console.log("  --chunk-strategy <auto|regex> - Chunking mode (default: regex; auto uses AST for code files)");
     console.log("  --timeout <minutes>          - Embed session cap in minutes (0 = no limit; default 30)");
     console.log("  --expand                    - Force query expansion (auto is the default; lex: skips)");
+    console.log("  --no-hyde                   - Disable HyDE (hypothetical document) in query expansion");
     console.log("");
     console.log("Embedding providers & disclosure:");
     console.log("  - Local embedding is the default. OpenAI requires explicit provider configuration and OPENAI_API_KEY.");
@@ -3911,10 +3920,6 @@ async function runDoctorDeviceChecks(nextSteps) {
     }
 }
 async function showDoctor() {
-    const storeInstance = getDoctorStore();
-    const db = storeInstance.db;
-    const pkg = readPackageJson();
-    const activeModels = resolveModelsForCli();
     let doctorConfig;
     try {
         doctorConfig = loadConfig();
@@ -3923,6 +3928,9 @@ async function showDoctor() {
         // The dedicated index-config check below reports parse errors. Keep the
         // remaining diagnostics available by falling back to DB/default config.
     }
+    const storeInstance = getDoctorStore({ reconcileConfig: doctorConfig });
+    const db = storeInstance.db;
+    const activeModels = resolveModelsForCli();
     const doctorEmbedding = resolveEmbeddingConfig({
         config: doctorConfig,
         dbConfig: readCanonicalEmbeddingConfig(db),
@@ -3933,7 +3941,7 @@ async function showDoctor() {
     const nextSteps = [];
     console.log(`${c.bold}QMD Doctor${c.reset}\n`);
     console.log(`Index: ${getDbPath()}`);
-    console.log(`Runtime: better-sqlite3`);
+    console.log(`Runtime: node:sqlite`);
     try {
         const row = db.prepare(`SELECT sqlite_version() AS version`).get();
         doctorCheck("SQLite runtime", true, row.version);
@@ -3941,8 +3949,7 @@ async function showDoctor() {
     catch (error) {
         doctorCheck("SQLite runtime", false, error instanceof Error ? error.message : String(error));
     }
-    const betterSqliteVersion = pkg.dependencies?.["better-sqlite3"] ?? pkg.devDependencies?.["better-sqlite3"] ?? "not declared";
-    doctorCheck("better-sqlite3 package", true, String(betterSqliteVersion));
+    doctorCheck("node:sqlite", true, process.versions.node);
     try {
         loadSqliteVec(db);
         const row = db.prepare(`SELECT vec_version() AS version`).get();

package/dist/db.d.ts

@@ -1,39 +1,26 @@
 /**
  * db.ts - SQLite database connection and extension management
  *
- * Provides Database export and connection management using better-sqlite3
- * and sqlite-vec.
+ * Provides a synchronous node:sqlite connection with QMD's transaction helper
+ * and sqlite-vec extension loading.
  */
-import BetterSqlite3 from "better-sqlite3";
+import { DatabaseSync, type StatementSync } from "node:sqlite";
 export type SQLiteValue = string | number | bigint | Buffer | Uint8Array | Float32Array | null;
 export type SQLiteParams = readonly SQLiteValue[];
-/**
- * Open a SQLite database using better-sqlite3.
- *
- * `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
- * opens.
- *
- * 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).
- */
+export type Transaction<TArgs extends unknown[], TResult> = ((...args: TArgs) => TResult) & {
+    deferred: (...args: TArgs) => TResult;
+    immediate: (...args: TArgs) => TResult;
+    exclusive: (...args: TArgs) => TResult;
+};
+/** Synchronous SQLite connection with QMD-compatible transactions. */
+export declare class Database extends DatabaseSync {
+    transaction<TArgs extends unknown[], TResult>(operation: (...args: TArgs) => TResult): Transaction<TArgs, TResult>;
+}
+/** Statement type used throughout QMD. */
+export type Statement<T extends SQLiteParams = SQLiteParams> = StatementSync;
+/** Open a writable QMD database using Node's built-in SQLite runtime. */
 export declare function openDatabase(path: string): Database;
 /** Open an existing database without changing journal mode, schema, or user data. */
 export declare function openReadOnlyDatabase(path: string): Database;
-/**
- * Database and Statement types used throughout QMD.
- */
-export type Database = BetterSqlite3.Database;
-export type Statement<T extends SQLiteParams = SQLiteParams> = BetterSqlite3.Statement<T>;
-/**
- * Load the sqlite-vec extension into a database.
- *
- * Throws with fix instructions when the extension is unavailable.
- */
+/** Load the sqlite-vec extension into a database. */
 export declare function loadSqliteVec(db: Database): void;

package/dist/db.js

@@ -1,11 +1,12 @@
 /**
  * db.ts - SQLite database connection and extension management
  *
- * Provides Database export and connection management using better-sqlite3
- * and sqlite-vec.
+ * Provides a synchronous node:sqlite connection with QMD's transaction helper
+ * and sqlite-vec extension loading.
  */
-import BetterSqlite3 from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
 import * as sqliteVec from "sqlite-vec";
+let savepointSequence = 0;
 function isBusyError(err) {
     if (typeof err !== "object" || err === null)
         return false;
@@ -18,12 +19,57 @@ function isBusyError(err) {
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/** Synchronous SQLite connection with QMD-compatible transactions. */
+export class Database extends DatabaseSync {
+    transaction(operation) {
+        const execute = (mode, args) => {
+            if (!this.isTransaction) {
+                this.exec(`BEGIN ${mode}`);
+                try {
+                    const result = operation(...args);
+                    this.exec("COMMIT");
+                    return result;
+                }
+                catch (error) {
+                    try {
+                        this.exec("ROLLBACK");
+                    }
+                    catch { }
+                    throw error;
+                }
+            }
+            const savepoint = `qmd_${++savepointSequence}`;
+            this.exec(`SAVEPOINT ${savepoint}`);
+            try {
+                const result = operation(...args);
+                this.exec(`RELEASE ${savepoint}`);
+                return result;
+            }
+            catch (error) {
+                try {
+                    this.exec(`ROLLBACK TO ${savepoint}`);
+                    this.exec(`RELEASE ${savepoint}`);
+                }
+                catch { }
+                throw error;
+            }
+        };
+        const transaction = ((...args) => execute("DEFERRED", args));
+        transaction.deferred = (...args) => execute("DEFERRED", args);
+        transaction.immediate = (...args) => execute("IMMEDIATE", args);
+        transaction.exclusive = (...args) => execute("EXCLUSIVE", args);
+        return transaction;
+    }
+}
+function resolveBusyTimeout() {
+    const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
+    const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
+}
 /**
  * Switch a connection to WAL, retrying on `SQLITE_BUSY` within the busy-timeout
- * budget. Unlike ordinary writes, migrating the journal needs a brief exclusive
- * lock and does NOT invoke the busy handler, so concurrent first-time opens of a
- * cold database throw "database is locked" even with `busy_timeout` set. Once the
- * database is already WAL the pragma is a cheap no-op that does not contend.
+ * budget. Migrating the journal needs a brief exclusive lock and does not invoke
+ * SQLite's busy handler on every supported runtime.
  */
 function enableWal(db, budgetMs) {
     const deadline = Date.now() + Math.max(budgetMs, 0);
@@ -39,46 +85,23 @@ function enableWal(db, budgetMs) {
         }
     }
 }
-/**
- * Open a SQLite database using better-sqlite3.
- *
- * `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
- * opens.
- *
- * 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).
- */
+/** Open a writable QMD database using Node's built-in SQLite runtime. */
 export function openDatabase(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;
-    db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+    const busyTimeoutMs = resolveBusyTimeout();
+    const db = new Database(path, { allowExtension: true, timeout: busyTimeoutMs });
     enableWal(db, busyTimeoutMs);
     return db;
 }
 /** Open an existing database without changing journal mode, schema, or user data. */
 export function openReadOnlyDatabase(path) {
-    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;
-    db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
-    return db;
+    const busyTimeoutMs = resolveBusyTimeout();
+    return new Database(path, {
+        readOnly: true,
+        allowExtension: true,
+        timeout: busyTimeoutMs,
+    });
 }
-/**
- * Load the sqlite-vec extension into a database.
- *
- * Throws with fix instructions when the extension is unavailable.
- */
+/** Load the sqlite-vec extension into a database. */
 export function loadSqliteVec(db) {
     try {
         sqliteVec.load(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/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

@@ -1208,7 +1208,7 @@ function rebuildFTSForCjkNormalization(db) {
             }
         });
         // Pull bounded batches and finalize each SELECT before starting the insert
-        // transaction. Holding a better-sqlite3 iterator open while beginning a
+        // transaction. Holding an SQLite iterator open while beginning a
         // transaction on the same connection raises "database is busy".
         const selectBatch = db.prepare(`
       SELECT d.id, d.collection, d.path, d.title, content.doc as body
@@ -1532,6 +1532,12 @@ export function setStoreGlobalContext(db, value) {
         db.prepare(`INSERT INTO store_config (key, value) VALUES ('global_context', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(value);
     }
 }
+function writeConfigSyncDiagnostic(db, diagnostic) {
+    db.prepare(`
+    INSERT INTO store_config (key, value) VALUES ('config_sync_diagnostic', ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(JSON.stringify(diagnostic));
+}
 function storeCollectionMatchesConfig(row, collection) {
     return row.path === collection.path
         && row.pattern === (collection.pattern || '**/*.md')
@@ -1556,12 +1562,14 @@ export function syncConfigToDb(db, config) {
             });
             const currentGlobalContext = getStoreGlobalContext(db);
             if (allMatch && currentGlobalContext === config.global_context) {
-                return {
+                const diagnostic = {
                     configHashChanged: false,
                     reconciled: false,
                     collections: { added: [], updated: [], removed: [] },
                     globalContextUpdated: false,
                 };
+                writeConfigSyncDiagnostic(db, diagnostic);
+                return diagnostic;
             }
         }
     }
@@ -2690,7 +2698,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);
@@ -2905,7 +2913,7 @@ export async function maybeAdoptLegacyEmbeddingFingerprint(store, model = DEFAUL
             return { checked: true, adopted: 0, reason: `legacy sample differs from current fingerprint (nearest ${nearest.hash_seq}, distance ${nearest.distance.toFixed(6)})` };
         }
         const update = withLazyContentVectorMigration(db, () => db.prepare(`UPDATE content_vectors SET embed_fingerprint = ? WHERE model = ? AND embed_fingerprint = ''`).run(fingerprint, model));
-        return { checked: true, adopted: update.changes, reason: `sample ${expectedHashSeq} matched current fingerprint at distance ${nearest.distance.toFixed(6)}` };
+        return { checked: true, adopted: Number(update.changes), reason: `sample ${expectedHashSeq} matched current fingerprint at distance ${nearest.distance.toFixed(6)}` };
     });
 }
 export function getIndexHealth(db, model = DEFAULT_EMBED_MODEL) {
@@ -2952,7 +2960,7 @@ export function clearCache(db) {
  */
 export function deleteLLMCache(db) {
     const result = db.prepare(`DELETE FROM llm_cache`).run();
-    return result.changes;
+    return Number(result.changes);
 }
 /**
  * Remove inactive document records (active = 0).
@@ -2976,7 +2984,7 @@ export function cleanupOrphanedContent(db) {
     DELETE FROM content
     WHERE hash NOT IN (SELECT DISTINCT hash FROM documents)
   `).run();
-    return result.changes;
+    return Number(result.changes);
 }
 /**
  * Count content hashes that would be unreferenced after inactive documents
@@ -4670,8 +4678,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 +4709,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 +4732,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 +5517,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 +5527,7 @@ export async function hybridQuery(store, query, options) {
             ? []
             : await store.expandQuery(query, undefined, expansionContext, {
                 requireResult: expansionDecision.reason === "explicit-force",
+                includeHyde,
             });
     }
     catch (error) {
@@ -5590,7 +5618,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 +5795,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wei840222/qmd",
-  "version": "2026.8.24",
+  "version": "2026.9.6",
   "packageManager": "pnpm@11.15.1",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
@@ -66,7 +66,6 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "@node-rs/jieba": "2.0.2",
-    "better-sqlite3": "^13.0.3",
     "fast-glob": "3.3.3",
     "node-llama-cpp": "3.20.0",
     "picomatch": "4.0.5",
@@ -88,7 +87,6 @@
   },
   "devDependencies": {
     "@oxlint/plugins": "1.78.0",
-    "@types/better-sqlite3": "7.6.13",
     "oxlint": "1.78.0",
     "tsx": "4.23.12",
     "vitest": "3.2.7"
@@ -113,7 +111,7 @@
     "typescript": "^5.9.3 || ^6.0.0-0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.16.0"
   },
   "keywords": [
     "markdown",