claude-flow 3.58.0 → 3.59.0

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.js

@@ -1438,7 +1438,7 @@ export async function bridgeListEntries(options) {
     if (!ctx)
         return null;
     try {
-        const { namespace, limit = 20, offset = 0, provenanceFilter } = options;
+        const { namespace, limit = 20, offset = 0, provenanceFilter, tags: requiredTags } = options;
         if (provenanceFilter?.some(p => !isValidProvenanceType(p)))
             return null;
         const filters = [];
@@ -1451,6 +1451,20 @@ export async function bridgeListEntries(options) {
             filters.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
             filterParams.push(...provenanceFilter);
         }
+        // Tags are stored as JSON-array TEXT (e.g. `["a","b"]`). Match each
+        // required tag as an exact element via SQLite's json_each so the filter
+        // runs in SQL instead of pulling the whole table into memory to filter
+        // there. A LIKE-based substring match is ASCII case-insensitive (so
+        // `prod` would match `PROD`) and matches raw JSON bytes rather than
+        // parsed array elements (so a tag literally containing `"prod` could
+        // false-match) — json_each compares real, decoded array values.
+        const tagFilter = Array.isArray(requiredTags)
+            ? requiredTags.filter((t) => typeof t === 'string' && t.length > 0)
+            : [];
+        for (const tag of tagFilter) {
+            filters.push(`EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)`);
+            filterParams.push(tag);
+        }
         const extraFilter = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
         // #2120 — `status IS NULL` accepted alongside `'active'`. Old
         // databases imported by the auto-memory bridge (before the status
@@ -1461,6 +1475,13 @@ export async function bridgeListEntries(options) {
         // "legacy-active" — the safe default for any entry that predates the
         // status column.
         const statusFilter = liveMemoryRowSql({ includeExpired: options.includeExpired });
+        // `|| 20` would treat an explicit `limit: 0` as falsy and silently
+        // substitute the default (returning 20 rows instead of the requested
+        // zero) — only fall back to the default when parsing genuinely failed.
+        const parsedLimit = parseInt(String(limit), 10);
+        const safeLimit = Number.isNaN(parsedLimit) ? 20 : parsedLimit;
+        const parsedOffset = parseInt(String(offset), 10);
+        const safeOffset = Number.isNaN(parsedOffset) ? 0 : parsedOffset;
         // Count
         let total = 0;
         try {
@@ -1474,15 +1495,26 @@ export async function bridgeListEntries(options) {
         // List
         const entries = [];
         try {
+            // Include tags so export/list can round-trip them.
             const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at
+        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at, tags
         FROM memory_entries
         WHERE ${statusFilter} ${extraFilter}
         ORDER BY updated_at DESC
         LIMIT ? OFFSET ?
       `);
-            const rows = stmt.all(...filterParams, options.includeEmbedding ? Math.min(limit, MAX_LIST_EMBEDDINGS) : limit, offset);
+            const rows = stmt.all(...filterParams, options.includeEmbedding ? Math.min(safeLimit, MAX_LIST_EMBEDDINGS) : safeLimit, safeOffset);
             for (const row of rows) {
+                let tags = [];
+                if (row.tags) {
+                    try {
+                        const parsed = typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags;
+                        if (Array.isArray(parsed)) {
+                            tags = parsed.filter((t) => typeof t === 'string');
+                        }
+                    }
+                    catch { /* invalid tags JSON */ }
+                }
                 const entry = {
                     // #2073: don't truncate id when content is requested — callers
                     // (notably memory_export) need the full id to round-trip via import.
@@ -1496,6 +1528,7 @@ export async function bridgeListEntries(options) {
                     expiresAt: row.expires_at ?? null,
                     hasEmbedding: !!(row.embedding && String(row.embedding).length > 10),
                     provenanceType: row.provenance_type || 'unknown',
+                    tags,
                 };
                 if (options.includeContent) {
                     entry.content = row.content || '';
@@ -1861,10 +1894,91 @@ export async function bridgeGetVectorSearchStatus(dbPath) {
         return null;
     }
 }
+/**
+ * #4203: RaBitQ pre-filter for the bridge's vector search.
+ *
+ * The index yields candidate ids from a 32×-compressed Hamming scan; each is
+ * reranked here with the same exact cosine similarity the exhaustive scan uses,
+ * so scores keep their meaning and only the scanned set shrinks (the candidate
+ * window `k * 2` is then widened 3× by `searchRabitq` itself).
+ *
+ * Returns null whenever the index cannot answer this query — WASM missing, too
+ * few vectors, or an index built for another store/dimension — so the caller
+ * runs its unchanged brute-force scan. Keyword/BM25 recall is unaffected: this
+ * only ever replaces the cosine scan.
+ */
+async function rabitqSearchAndRerank(db, queryEmbedding, options) {
+    try {
+        const { ensureRabitqIndex, searchRabitq } = await import('./rabitq-index.js');
+        const ready = await ensureRabitqIndex({ dbPath: options.dbPath, dimensions: queryEmbedding.length });
+        if (!ready)
+            return null;
+        const candidates = await searchRabitq(queryEmbedding, {
+            k: options.k * 2,
+            namespace: options.namespace,
+        });
+        if (!candidates || candidates.length === 0)
+            return null;
+        // Fetch exactly the candidates (id is the primary key) instead of the
+        // 10k-row full scan; chunked to stay well inside SQLite's parameter limit.
+        const rowsById = new Map();
+        const ids = candidates.map(c => c.id);
+        for (let i = 0; i < ids.length; i += 500) {
+            const chunk = ids.slice(i, i + 500);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = db.prepare(`
+        SELECT id, key, namespace, content, embedding
+        FROM memory_entries
+        WHERE id IN (${placeholders}) AND ${liveMemoryRowSql()} AND embedding IS NOT NULL
+      `).all(...chunk);
+            for (const row of rows) {
+                let embedding;
+                try {
+                    embedding = JSON.parse(row.embedding);
+                }
+                catch {
+                    continue;
+                }
+                if (!Array.isArray(embedding) || embedding.length !== queryEmbedding.length)
+                    continue;
+                rowsById.set(String(row.id), {
+                    key: row.key || String(row.id),
+                    namespace: row.namespace || 'default',
+                    content: row.content || '',
+                    score: cosineSim(queryEmbedding, embedding),
+                });
+            }
+        }
+        const results = [];
+        for (const candidate of candidates) {
+            const row = rowsById.get(candidate.id);
+            if (!row || row.score < options.threshold)
+                continue;
+            results.push({
+                id: candidate.id.substring(0, 12),
+                key: row.key || candidate.id.substring(0, 15),
+                content: row.content.substring(0, 60) + (row.content.length > 60 ? '...' : ''),
+                score: row.score,
+                namespace: row.namespace,
+            });
+        }
+        if (results.length === 0)
+            return null;
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.k);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Search AgentDB v3's embedder + SQLite entries via a full-table scan and
  * brute-force cosine similarity. NOT HNSW-accelerated — see #2922. Returns
  * null if unavailable.
+ *
+ * #4203: when a RaBitQ index is available the Hamming-scan candidate set is
+ * reranked exactly instead of scanning the whole table; the exhaustive loop
+ * below stays the fallback, so results and scores keep their meaning.
  */
 export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPath) {
     if (!operationContext.getStore()?.active)
@@ -1881,6 +1995,17 @@ export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPa
         const nsFilter = options?.namespace && options.namespace !== 'all'
             ? `AND namespace = ?`
             : '';
+        // #4203: try the RaBitQ pre-filter before the exhaustive scan below. A null
+        // result (no index / unavailable / nothing above threshold) falls through
+        // to the unchanged brute-force path.
+        const accelerated = await rabitqSearchAndRerank(ctx.db, queryEmbedding, {
+            k,
+            threshold,
+            namespace: options?.namespace,
+            dbPath,
+        });
+        if (accelerated)
+            return accelerated;
         let rows;
         try {
             // #2982/#2976: same unordered pre-rank truncation as bridgeSearchEntries
@@ -3361,6 +3486,41 @@ export async function bridgeGetAllEmbeddings(options) {
         return null;
     }
 }
+/**
+ * Count the embeddings `bridgeGetAllEmbeddings()` would export (#4203).
+ * RaBitQ's auto-build uses this as its cheap "has the corpus drifted?" probe —
+ * a COUNT instead of re-reading every embedding blob. With `dimensions` it
+ * counts only rows build() would keep, so the drift ratio compares like with
+ * like. Returns null if the bridge is unavailable.
+ */
+export async function bridgeCountEmbeddings(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeCountEmbeddings(options));
+    const registry = await getRegistry(options?.dbPath);
+    if (!registry)
+        return null;
+    const ctx = getDb(registry);
+    if (!ctx)
+        return null;
+    const dims = options?.dimensions;
+    try {
+        if (dims != null) {
+            try {
+                const row = ctx.db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL AND json_array_length(embedding) = ?`).get(dims);
+                return row?.cnt ?? 0;
+            }
+            catch {
+                // JSON1 unavailable in this SQLite build — fall through to the
+                // unfiltered count rather than losing the probe entirely.
+            }
+        }
+        const row = ctx.db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL`).get();
+        return row?.cnt ?? 0;
+    }
+    catch {
+        return null;
+    }
+}
 // ===== Utility =====
 function cosineSim(a, b) {
     if (!a || !b || a.length === 0 || b.length === 0)

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts

@@ -513,6 +513,8 @@ export declare function listEntries(options: {
     includeEmbedding?: boolean;
     /** #4056: also return rows whose TTL has passed (with `expiresAt`). For cleanup only; normal reads hide them. */
     includeExpired?: boolean;
+    /** Require entries to include all of these tags (AND). */
+    tags?: string[];
 }): Promise<{
     success: boolean;
     entries: {
@@ -531,6 +533,8 @@ export declare function listEntries(options: {
         provenanceType?: string;
         /** ADR-472: present when `includeEmbedding: true` and the row has a valid stored vector. */
         embeddingQ8?: EmbeddingQ8;
+        /** Tag set stored with the entry (empty array when none). */
+        tags?: string[];
     }[];
     total: number;
     error?: string;

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -2808,7 +2808,11 @@ export async function searchEntries(options) {
         const queryEmbedding = queryEmb.embedding;
         // Try RaBitQ pre-filter first (32× compressed Hamming scan)
         try {
-            const { searchRabitq } = await import('./rabitq-index.js');
+            const { ensureRabitqIndex, searchRabitq } = await import('./rabitq-index.js');
+            // #4203: build/rebuild on demand — without this the index was only ever
+            // populated by the explicit `embeddings_rabitq_build` tool, so this
+            // pre-filter always missed.
+            await ensureRabitqIndex({ dbPath, dimensions: queryEmbedding.length });
             const rabitqCandidates = await searchRabitq(queryEmbedding, { k: limit * 2, namespace: effectiveNamespace });
             if (rabitqCandidates && rabitqCandidates.length > 0) {
                 // Rerank candidates with exact cosine similarity from SQLite
@@ -3043,7 +3047,7 @@ export async function listEntries(options) {
             return bridgeResult;
     }
     // Fallback: raw sql.js
-    const { namespace, limit = 20, offset = 0, dbPath: customPath, provenanceFilter } = options;
+    const { namespace, limit = 20, offset = 0, dbPath: customPath, provenanceFilter, tags: requiredTags, } = options;
     const swarmDir = getMemoryRoot();
     const dbPath = customPath || path.join(swarmDir, 'memory.db');
     try {
@@ -3065,18 +3069,41 @@ export async function listEntries(options) {
         // #2120 — accept `status IS NULL` alongside `'active'`. Old DBs
         // that predate the status column may have NULL after migration.
         // See memory-bridge.ts:bridgeListEntries for full context.
-        // Get total count
         const whereClauses = [liveMemoryRowSql({ includeExpired: options.includeExpired })];
         const whereParams = [];
         if (namespace) {
             whereClauses.push('namespace = ?');
             whereParams.push(namespace);
         }
+        // ADR-323: restrict to the requested provenance types. This must be
+        // ANDed alongside any tags filter below, never replaced by it — dropping
+        // this clause lets unverified user_claim rows leak into results that
+        // are supposed to be tool_result-only.
         if (provenanceFilter?.length) {
             whereClauses.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
             whereParams.push(...provenanceFilter);
         }
+        // Tags are stored as JSON-array TEXT (e.g. `["a","b"]`). Match each
+        // required tag as an exact element via SQLite's json_each so a tag of
+        // `prod` can't be satisfied by a substring like `"prod` or by a
+        // differently-cased value like `PROD` (LIKE is ASCII case-insensitive
+        // and matches raw JSON-array bytes, not parsed array elements).
+        const tagFilter = Array.isArray(requiredTags)
+            ? requiredTags.filter((t) => typeof t === 'string' && t.length > 0)
+            : [];
+        for (const tag of tagFilter) {
+            whereClauses.push(`EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)`);
+            whereParams.push(tag);
+        }
         const whereSql = whereClauses.join(' AND ');
+        // `|| 100` would treat an explicit `limit: 0` as falsy and silently
+        // substitute the default (returning rows instead of the requested
+        // zero) — only fall back to the default when parsing genuinely failed.
+        const parsedLimit = parseInt(String(limit), 10);
+        const safeLimit = Number.isNaN(parsedLimit) ? 100 : parsedLimit;
+        const parsedOffset = parseInt(String(offset), 10);
+        const safeOffset = Number.isNaN(parsedOffset) ? 0 : parsedOffset;
+        // Get total count
         const countStmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${whereSql}`);
         if (whereParams.length > 0)
             countStmt.bind(whereParams);
@@ -3085,50 +3112,56 @@ export async function listEntries(options) {
             countRows.push(countStmt.get());
         }
         countStmt.free();
-        const countResult = countRows.length > 0 ? [{ values: countRows }] : [];
-        const total = countResult[0]?.values?.[0]?.[0] || 0;
-        // Get entries
-        const safeLimit = Math.min(parseInt(String(limit), 10) || 100, options.includeEmbedding ? MAX_LIST_EMBEDDINGS : Number.MAX_SAFE_INTEGER);
-        const safeOffset = parseInt(String(offset), 10) || 0;
-        // #2120 — same NULL-as-active acceptance as the count above.
-        const listStmt = db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at
+        const total = countRows[0]?.[0] || 0;
+        // Get entries. ADR-472: embedding rows are capped at MAX_LIST_EMBEDDINGS.
+        const listLimit = options.includeEmbedding ? Math.min(safeLimit, MAX_LIST_EMBEDDINGS) : safeLimit;
+        // Include tags so export/list can round-trip them.
+        const listStmt = db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at, tags
        FROM memory_entries WHERE ${whereSql}
        ORDER BY updated_at DESC LIMIT ? OFFSET ?`);
-        listStmt.bind([...whereParams, safeLimit, safeOffset]);
+        listStmt.bind([...whereParams, listLimit, safeOffset]);
         const listRows = [];
         while (listStmt.step()) {
             listRows.push(listStmt.get());
         }
         listStmt.free();
-        const result = listRows.length > 0 ? [{ values: listRows }] : [];
         const entries = [];
-        if (result[0]?.values) {
-            for (const row of result[0].values) {
-                const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal, expiresAtVal] = row;
-                const entry = {
-                    // #2073: don't truncate id when content is requested — callers
-                    // (notably memory_export) need the full id to round-trip via import.
-                    id: options.includeContent ? String(id) : String(id).substring(0, 20),
-                    key: key || String(id).substring(0, 15),
-                    namespace: ns || 'default',
-                    size: (content || '').length,
-                    accessCount: accessCount || 0,
-                    createdAt: createdAt || new Date().toISOString(),
-                    updatedAt: updatedAt || new Date().toISOString(),
-                    expiresAt: expiresAtVal ?? null,
-                    hasEmbedding: !!embedding && embedding.length > 10,
-                    provenanceType: provenanceTypeVal || 'unknown'
-                };
-                if (options.includeContent) {
-                    entry.content = content || '';
-                }
-                if (options.includeEmbedding) {
-                    const q8 = encodeEmbeddingQ8(embedding);
-                    if (q8)
-                        entry.embeddingQ8 = q8;
+        for (const row of listRows) {
+            const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal, expiresAtVal, tagsJson] = row;
+            let tags = [];
+            if (tagsJson) {
+                try {
+                    const parsed = JSON.parse(tagsJson);
+                    if (Array.isArray(parsed)) {
+                        tags = parsed.filter((t) => typeof t === 'string');
+                    }
                 }
-                entries.push(entry);
+                catch { /* invalid tags JSON */ }
+            }
+            const entry = {
+                // #2073: don't truncate id when content is requested — callers
+                // (notably memory_export) need the full id to round-trip via import.
+                id: options.includeContent ? String(id) : String(id).substring(0, 20),
+                key: key || String(id).substring(0, 15),
+                namespace: ns || 'default',
+                size: (content || '').length,
+                accessCount: accessCount || 0,
+                createdAt: createdAt || new Date().toISOString(),
+                updatedAt: updatedAt || new Date().toISOString(),
+                expiresAt: expiresAtVal ?? null,
+                hasEmbedding: !!embedding && embedding.length > 10,
+                provenanceType: provenanceTypeVal || 'unknown',
+                tags,
+            };
+            if (options.includeContent) {
+                entry.content = content || '';
+            }
+            if (options.includeEmbedding) {
+                const q8 = encodeEmbeddingQ8(embedding);
+                if (q8)
+                    entry.embeddingQ8 = q8;
             }
+            entries.push(entry);
         }
         db.close();
         return { success: true, entries, total };

package/v3/@claude-flow/cli/dist/src/memory/rabitq-index.d.ts

@@ -9,6 +9,11 @@
  *  1. build() — bulk-load all embeddings from SQLite into the WASM index
  *  2. search() — fast Hamming scan → candidate ids → caller reranks
  *  3. rebuild() — called when entry count drifts >20% from last build
+ *
+ * #4203: step 3 is driven by `ensureRabitqIndex()`, which the search paths
+ * call before `searchRabitq()`. Previously the only caller of the build was
+ * the explicit `embeddings_rabitq_build` tool, so the index was effectively
+ * never populated and every `searchRabitq()` returned null.
  */
 /**
  * Build or rebuild the RaBitQ index from SQLite embeddings.
@@ -46,6 +51,20 @@ export declare function searchRabitq(queryEmbedding: number[], options?: {
  * Check if the RaBitQ index needs rebuilding.
  */
 export declare function shouldRebuildRabitq(currentEntryCount: number): Promise<boolean>;
+/**
+ * Auto-build / auto-rebuild entry point (#4203).
+ *
+ * Search paths call this before `searchRabitq()`: it lets `shouldRebuildRabitq()`
+ * decide whether the index is missing or has drifted past the 20% threshold and
+ * builds it when so. Never throws — a missing WASM module, an unreadable store
+ * or an index built for another store/dimension just leaves the caller's
+ * existing non-RaBitQ path untouched. Returns whether an index usable for these
+ * options exists afterwards.
+ */
+export declare function ensureRabitqIndex(options?: {
+    dbPath?: string;
+    dimensions?: number;
+}): Promise<boolean>;
 /**
  * Get RaBitQ index status.
  */

package/v3/@claude-flow/cli/dist/src/memory/rabitq-index.js

@@ -9,14 +9,27 @@
  *  1. build() — bulk-load all embeddings from SQLite into the WASM index
  *  2. search() — fast Hamming scan → candidate ids → caller reranks
  *  3. rebuild() — called when entry count drifts >20% from last build
+ *
+ * #4203: step 3 is driven by `ensureRabitqIndex()`, which the search paths
+ * call before `searchRabitq()`. Previously the only caller of the build was
+ * the explicit `embeddings_rabitq_build` tool, so the index was effectively
+ * never populated and every `searchRabitq()` returned null.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 const RABITQ_SEED = 42n;
 const RABITQ_RERANK_FACTOR = 20;
 const REBUILD_DRIFT_THRESHOLD = 0.2; // rebuild when count drifts >20%
+/** #4203: minimum gap between auto-build attempts, so a store that is still
+ *  too small cannot turn every search into a build attempt. */
+const AUTO_BUILD_RETRY_MS = 60_000;
+const RABITQ_UNAVAILABLE_ERROR = '@ruvector/rabitq-wasm not available';
 let rabitqState = null;
 let rabitqInitializing = false;
+let lastAutoBuildAttempt = 0;
+/** Set once the WASM module is known to be missing for this process: retrying
+ *  the same failing dynamic import on every search buys nothing. */
+let autoBuildDisabled = false;
 async function loadRabitqModule() {
     try {
         const mod = await import('@ruvector/rabitq-wasm');
@@ -50,7 +63,7 @@ export async function buildRabitqIndex(options) {
         const mod = await loadRabitqModule();
         if (!mod) {
             rabitqInitializing = false;
-            return { success: false, vectorCount: 0, dimensions: 0, compressionRatio: 0, buildTimeMs: 0, error: '@ruvector/rabitq-wasm not available' };
+            return { success: false, vectorCount: 0, dimensions: 0, compressionRatio: 0, buildTimeMs: 0, error: RABITQ_UNAVAILABLE_ERROR };
         }
         const dimensions = options?.dimensions ?? 384;
         const swarmDir = path.resolve(process.cwd(), '.swarm');
@@ -126,6 +139,7 @@ export async function buildRabitqIndex(options) {
             dimensions,
             builtAt: Date.now(),
             vectorCount: entries.length,
+            sourcePath: options?.dbPath ? path.resolve(options.dbPath) : undefined,
         };
         // Persist metadata for fast reload hint
         try {
@@ -226,6 +240,108 @@ export async function shouldRebuildRabitq(currentEntryCount) {
     const drift = Math.abs(currentEntryCount - rabitqState.vectorCount) / Math.max(rabitqState.vectorCount, 1);
     return drift > REBUILD_DRIFT_THRESHOLD;
 }
+/**
+ * Whether the in-memory index can answer a query for this store/dimension.
+ * `undefined` dbPath means "the default store", matching build's own default.
+ */
+function isRabitqUsable(options) {
+    if (!rabitqState)
+        return false;
+    if (options?.dimensions != null && rabitqState.dimensions !== options.dimensions)
+        return false;
+    const sourcePath = options?.dbPath ? path.resolve(options.dbPath) : undefined;
+    return rabitqState.sourcePath === sourcePath;
+}
+/**
+ * Count the rows `buildRabitqIndex()` would load, using the cheapest source
+ * available: the bridge's COUNT (WAL-visible, same rows build prefers) with a
+ * sql.js COUNT of the same file as fallback. Returns 0 when neither is
+ * readable, which simply leaves the caller on its non-RaBitQ path.
+ */
+async function countIndexableEntries(options) {
+    const dimensions = options?.dimensions ?? 384;
+    try {
+        const { bridgeCountEmbeddings } = await import('./memory-bridge.js');
+        const bridgeCount = await bridgeCountEmbeddings({ dimensions, dbPath: options?.dbPath });
+        if (bridgeCount !== null)
+            return bridgeCount;
+    }
+    catch { /* bridge unavailable, fall through */ }
+    const dbPath = options?.dbPath
+        ? path.resolve(options.dbPath)
+        : path.join(path.resolve(process.cwd(), '.swarm'), 'memory.db');
+    if (!fs.existsSync(dbPath))
+        return 0;
+    let db = null;
+    try {
+        const initSqlJs = (await import('sql.js')).default;
+        const SQL = await initSqlJs();
+        db = new SQL.Database(fs.readFileSync(dbPath));
+        const count = (dimFilter) => db.exec(`
+      SELECT COUNT(*) FROM memory_entries
+      WHERE status = 'active' AND embedding IS NOT NULL${dimFilter}
+    `);
+        let result;
+        try {
+            // Same rows build() keeps: only embeddings of the requested width.
+            result = count(` AND json_array_length(embedding) = ${dimensions}`);
+        }
+        catch {
+            result = count('');
+        }
+        return Number(result[0]?.values?.[0]?.[0] ?? 0);
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Auto-build / auto-rebuild entry point (#4203).
+ *
+ * Search paths call this before `searchRabitq()`: it lets `shouldRebuildRabitq()`
+ * decide whether the index is missing or has drifted past the 20% threshold and
+ * builds it when so. Never throws — a missing WASM module, an unreadable store
+ * or an index built for another store/dimension just leaves the caller's
+ * existing non-RaBitQ path untouched. Returns whether an index usable for these
+ * options exists afterwards.
+ */
+export async function ensureRabitqIndex(options) {
+    if (autoBuildDisabled || rabitqInitializing)
+        return isRabitqUsable(options);
+    const dimensions = options?.dimensions ?? 384;
+    const now = Date.now();
+    if (now - lastAutoBuildAttempt < AUTO_BUILD_RETRY_MS)
+        return isRabitqUsable(options);
+    lastAutoBuildAttempt = now;
+    let currentEntryCount = 0;
+    try {
+        currentEntryCount = await countIndexableEntries({ dbPath: options?.dbPath, dimensions });
+    }
+    catch {
+        currentEntryCount = 0;
+    }
+    if (isRabitqUsable(options)) {
+        // Same store and width: rebuild only once the corpus has drifted >20%.
+        if (!(await shouldRebuildRabitq(currentEntryCount)))
+            return true;
+    }
+    else if (!rabitqState) {
+        // Nothing built yet: honour the "enough vectors to be worth it" floor.
+        if (!(await shouldRebuildRabitq(currentEntryCount)))
+            return false;
+    }
+    // Either the index is stale for this store/width, or the entry count drifted.
+    const result = await buildRabitqIndex({ dbPath: options?.dbPath, dimensions });
+    if (!result.success && result.error === RABITQ_UNAVAILABLE_ERROR)
+        autoBuildDisabled = true;
+    return isRabitqUsable(options);
+}
 /**
  * Get RaBitQ index status.
  */