claude-flow 3.56.9 → 3.57.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js

@@ -12,6 +12,35 @@ import { executeAgentTask } from './agent-execute-core.js';
 const STORAGE_DIR = '.claude-flow';
 const WORKFLOW_DIR = 'workflows';
 const WORKFLOW_FILE = 'store.json';
+function parseCondition(when) {
+    if (typeof when !== 'string' || !when.trim()) {
+        return new Error('condition step requires a non-empty config.when');
+    }
+    const expression = when.trim();
+    if (expression === 'true' || expression === 'false') {
+        return { constant: expression === 'true' };
+    }
+    const match = expression.match(/^([a-zA-Z_]\w*)\s*===?\s*(?:'([^']*)'|"([^"]*)"|(-?\d+(?:\.\d+)?)|(true|false))$/);
+    if (!match) {
+        return new Error('condition config.when must compare a variable to a quoted string, number, or boolean using == or ===');
+    }
+    const expected = match[2] ?? match[3] ?? (match[4] !== undefined ? Number(match[4]) : match[5] === 'true');
+    return { variable: match[1], expected };
+}
+function validateExecutableStep(step) {
+    if (step.type === 'parallel' || step.type === 'loop') {
+        return `step type '${step.type}' is not implemented by the workflow runtime`;
+    }
+    if (step.type === 'condition') {
+        const parsed = parseCondition(step.config?.when);
+        if (parsed instanceof Error)
+            return parsed.message;
+    }
+    else if (step.type !== 'task' && step.type !== 'wait') {
+        return `unsupported workflow step type '${step.type}'`;
+    }
+    return undefined;
+}
 function getWorkflowDir() {
     return join(getProjectCwd(), STORAGE_DIR, WORKFLOW_DIR);
 }
@@ -181,8 +210,8 @@ export const workflowTools = [
                         type: 'object',
                         properties: {
                             name: { type: 'string' },
-                            type: { type: 'string', enum: ['task', 'condition', 'parallel', 'loop', 'wait'] },
-                            config: { type: 'object' },
+                            type: { type: 'string', enum: ['task', 'condition', 'wait'] },
+                            config: { type: 'object', description: 'Condition steps require config.when; parallel and loop steps are not yet supported' },
                         },
                     },
                 },
@@ -209,6 +238,11 @@ export const workflowTools = [
                 config: s.config || {},
                 status: 'pending',
             }));
+            for (const step of steps) {
+                const error = validateExecutableStep(step);
+                if (error)
+                    return { success: false, error: `${step.stepId} (${step.name}): ${error}` };
+            }
             const workflow = {
                 workflowId,
                 name: input.name,
@@ -257,6 +291,20 @@ export const workflowTools = [
             if (workflow.status === 'running') {
                 return { workflowId, error: 'Workflow already running' };
             }
+            // Older stored workflows may predate creation-time validation. Reject
+            // unsupported steps before dispatching any task with side effects.
+            for (const step of workflow.steps) {
+                const error = validateExecutableStep(step);
+                if (error) {
+                    workflow.status = 'failed';
+                    workflow.error = `${step.stepId} (${step.name}): ${error}`;
+                    step.status = 'failed';
+                    step.result = { error: workflow.error };
+                    workflow.completedAt = new Date().toISOString();
+                    saveWorkflowStore(store);
+                    return { workflowId, status: 'failed', failedStep: step.stepId, error: workflow.error };
+                }
+            }
             // Indices may name a step or the end boundary (used when resuming
             // after the final step). Reject invalid control flow before any writes.
             const validIndex = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= workflow.steps.length;
@@ -382,19 +430,14 @@ export const workflowTools = [
                         stepEntry = { stepId: step.stepId, type: 'wait', status: 'completed', durationMs: ms };
                     }
                     else if (step.type === 'condition') {
-                        // Simple condition: config.when is a JS expression evaluated against workflow.variables.
-                        // For safety, we only support `var === 'value'` or `var === number`.
                         const cfg = step.config;
-                        const expr = String(cfg.when || 'true').trim();
-                        const m = expr.match(/^([a-zA-Z_][\w]*)\s*===?\s*(['\"])?([^'\"]*)\2?$/);
-                        let truthy = false;
-                        if (m) {
-                            const v = workflow.variables[m[1]];
-                            const expected = m[2] ? m[3] : Number(m[3]);
-                            truthy = v === expected;
-                        }
-                        else if (expr === 'true')
-                            truthy = true;
+                        const parsed = parseCondition(cfg.when);
+                        if (parsed instanceof Error)
+                            throw parsed;
+                        const truthy = 'constant' in parsed
+                            ? parsed.constant
+                            : workflow.variables[parsed.variable] === parsed.expected;
+                        const expr = String(cfg.when).trim();
                         step.result = { conditionExpr: expr, truthy };
                         // condition can declare a target step index to jump to via cfg.thenStep / cfg.elseStep
                         if (typeof cfg.thenStep === 'number' && truthy)
@@ -404,9 +447,7 @@ export const workflowTools = [
                         stepEntry = { stepId: step.stepId, type: 'condition', status: 'completed' };
                     }
                     else {
-                        // parallel/loop are deferred — mark skipped honestly rather than mock-completing.
-                        step.result = { _note: `step type '${step.type}' not yet implemented in runtime` };
-                        stepEntry = { stepId: step.stepId, type: step.type, status: 'skipped' };
+                        throw new Error(`step type '${step.type}' is not implemented by the workflow runtime`);
                     }
                     step.status = stepEntry.status === 'skipped' ? 'skipped' : 'completed';
                     step.completedAt = new Date().toISOString();
@@ -906,6 +947,14 @@ export const workflowTools = [
                         const agentSet = new Set();
                         steps.forEach((s, i) => {
                             const step = (s ?? {});
+                            if (typeof step.type === 'string') {
+                                const error = validateExecutableStep({
+                                    type: step.type,
+                                    config: (step.config ?? {}),
+                                });
+                                if (error)
+                                    errors.push({ line: i + 1, message: `step ${i + 1}: ${error}`, severity: 'error' });
+                            }
                             // Match workflow_execute: control steps do not dispatch agents,
                             // and task steps use config.agentId or the workflow default.
                             const config = step.config;

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

@@ -175,8 +175,12 @@ declare class LocalReasoningBank {
      * Deduplicates by content: if a pattern with the same content already
      * exists, the existing entry is updated (bumped usageCount, higher
      * confidence wins, refreshed lastUsedAt) instead of adding a duplicate.
+     *
+     * Returns true only when a NEW pattern was added (#3979 item 4): callers that
+     * keep a "patterns learned" counter must not count a merge or an update of an
+     * existing pattern as a newly learned one.
      */
-    store(pattern: Omit<StoredPattern, 'usageCount' | 'createdAt' | 'lastUsedAt'> & Partial<StoredPattern>): void;
+    store(pattern: Omit<StoredPattern, 'usageCount' | 'createdAt' | 'lastUsedAt'> & Partial<StoredPattern>): boolean;
     /**
      * Find similar patterns by embedding.
      *

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

@@ -10,11 +10,13 @@
  *
  * @module v3/cli/intelligence
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { resolveTrainingBackend } from '../ruvector/lora-adapter.js';
+import { getProjectCwd } from '../mcp-tools/types.js';
+import { withStatsFileLock } from './stats-file-lock.js';
 // ============================================================================
 // Persistence Configuration
 // ============================================================================
@@ -24,7 +26,11 @@ import { resolveTrainingBackend } from '../ruvector/lora-adapter.js';
  * falling back to home directory
  */
 function getDataDir() {
-    const cwd = process.cwd();
+    // Every MCP tool resolves `.claude-flow/` against the project root
+    // (CLAUDE_FLOW_CWD when set), so the neural stats/patterns must too —
+    // otherwise an MCP server whose process cwd differs from the project
+    // writes learning state where nothing reads it.
+    const cwd = getProjectCwd();
     const localDir = join(cwd, '.claude-flow', 'neural');
     const homeDir = join(homedir(), '.claude-flow', 'neural');
     // Prefer local directory if .claude-flow exists
@@ -429,6 +435,10 @@ class LocalReasoningBank {
      * Deduplicates by content: if a pattern with the same content already
      * exists, the existing entry is updated (bumped usageCount, higher
      * confidence wins, refreshed lastUsedAt) instead of adding a duplicate.
+     *
+     * Returns true only when a NEW pattern was added (#3979 item 4): callers that
+     * keep a "patterns learned" counter must not count a merge or an update of an
+     * existing pattern as a newly learned one.
      */
     store(pattern) {
         const now = Date.now();
@@ -448,6 +458,9 @@ class LocalReasoningBank {
             if (idx >= 0) {
                 this.patternList[idx] = stored;
             }
+            this.patterns.set(pattern.id, stored);
+            this.saveToDisk();
+            return false;
         }
         else {
             // Check for content-duplicate before inserting a new entry
@@ -462,7 +475,7 @@ class LocalReasoningBank {
                 // Keep the Map in sync with the mutated object
                 this.patterns.set(contentDupe.id, contentDupe);
                 this.saveToDisk();
-                return;
+                return false;
             }
             // Evict oldest if at capacity
             if (this.patterns.size >= this.maxSize) {
@@ -476,6 +489,7 @@ class LocalReasoningBank {
         this.patterns.set(pattern.id, stored);
         // Trigger persistence (debounced)
         this.saveToDisk();
+        return true;
     }
     /**
      * Find similar patterns by embedding.
@@ -629,6 +643,36 @@ let globalStats = {
     signalsProcessed: 0,
     lastAdaptation: null
 };
+/**
+ * Increments made by THIS process that have not yet been merged into
+ * stats.json. Persistence is delta-based: several processes (MCP server,
+ * hook one-shots, the worker daemon) share one stats.json, and each holds
+ * its own module-level globalStats. Writing the local snapshot verbatim let
+ * any writer erase every other writer's progress — notably the
+ * memory-bridge `recordSignalProcessed()` path, which persists without ever
+ * loading the file, reset `trajectoriesRecorded` to 0 on disk every 16
+ * writes. Merging deltas makes the counters monotonic across processes.
+ */
+let pendingDelta = {
+    trajectoriesRecorded: 0,
+    patternsLearned: 0,
+    signalsProcessed: 0,
+};
+let persistedStatsLoaded = false;
+function bumpStat(key, n = 1) {
+    globalStats[key] = (globalStats[key] ?? 0) + n;
+    pendingDelta[key] += n;
+}
+function readStatsFile() {
+    try {
+        // Read-only callers keep their unavailable-on-error contract, while invalid
+        // disk values cannot poison local state and a later repaired-file flush.
+        return readStatsForWrite(getStatsPath());
+    }
+    catch {
+        return null;
+    }
+}
 // ============================================================================
 // Stats Persistence
 // ============================================================================
@@ -636,36 +680,99 @@ let globalStats = {
  * Load persisted stats from disk
  */
 function loadPersistedStats() {
+    persistedStatsLoaded = true;
+    const data = readStatsFile();
+    if (!data)
+        return;
+    // #2245: previously only restored trajectoriesRecorded — patternsLearned
+    // and signalsProcessed reset to zero on every restart, masking real
+    // learning progress in the dashboards. Unsaved local increments are
+    // re-applied on top so a late load never drops them.
+    globalStats.trajectoriesRecorded = (data.trajectoriesRecorded ?? 0) + pendingDelta.trajectoriesRecorded;
+    globalStats.patternsLearned = (data.patternsLearned ?? 0) + pendingDelta.patternsLearned;
+    globalStats.signalsProcessed = (data.signalsProcessed ?? 0) + pendingDelta.signalsProcessed;
+    globalStats.lastAdaptation = maxTimestamp(data.lastAdaptation ?? null, globalStats.lastAdaptation);
+}
+function maxTimestamp(a, b) {
+    if (a == null)
+        return b;
+    if (b == null)
+        return a;
+    return Math.max(a, b);
+}
+/** Missing files are first use; unreadable or invalid files must not be replaced. */
+function readStatsForWrite(path) {
+    let text;
     try {
-        const path = getStatsPath();
-        if (existsSync(path)) {
-            const data = JSON.parse(readFileSync(path, 'utf-8'));
-            if (data && typeof data === 'object') {
-                // #2245: previously only restored trajectoriesRecorded — patternsLearned
-                // and signalsProcessed reset to zero on every restart, masking real
-                // learning progress in the dashboards.
-                globalStats.trajectoriesRecorded = data.trajectoriesRecorded ?? 0;
-                globalStats.patternsLearned = data.patternsLearned ?? 0;
-                globalStats.signalsProcessed = data.signalsProcessed ?? 0;
-                globalStats.lastAdaptation = data.lastAdaptation ?? null;
-            }
-        }
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
     }
     catch {
-        // Ignore load errors, start fresh
+        throw Object.assign(new Error('Invalid learning stats JSON'), { code: 'EINVALIDSTATS' });
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw Object.assign(new Error('Invalid learning stats object'), { code: 'EINVALIDSTATS' });
     }
+    for (const key of ['trajectoriesRecorded', 'patternsLearned', 'signalsProcessed']) {
+        const value = data[key];
+        // Older files may omit a counter, but present counters must be exact counts.
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+            throw Object.assign(new Error(`Invalid learning stats field: ${key}`), { code: 'EINVALIDSTATS' });
+        }
+    }
+    const timestamp = data.lastAdaptation;
+    if (timestamp != null && (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp < 0)) {
+        throw Object.assign(new Error('Invalid learning stats timestamp'), { code: 'EINVALIDSTATS' });
+    }
+    return data;
 }
-/**
- * Save stats to disk
- */
+/** Merge pending deltas under the cooperating-writer lock, then adopt committed totals. */
 function savePersistedStats() {
+    let statsPath;
     try {
-        ensureDataDir();
-        const path = getStatsPath();
-        writeFileSync(path, JSON.stringify(globalStats, null, 2), 'utf-8');
+        statsPath = join(ensureDataDir(), 'stats.json');
+        withStatsFileLock(statsPath, (path) => {
+            const disk = readStatsForWrite(path);
+            const merged = disk
+                ? {
+                    trajectoriesRecorded: (disk.trajectoriesRecorded ?? 0) + pendingDelta.trajectoriesRecorded,
+                    patternsLearned: (disk.patternsLearned ?? 0) + pendingDelta.patternsLearned,
+                    signalsProcessed: (disk.signalsProcessed ?? 0) + pendingDelta.signalsProcessed,
+                    lastAdaptation: maxTimestamp(disk.lastAdaptation ?? null, globalStats.lastAdaptation),
+                }
+                : { ...globalStats };
+            for (const key of ['trajectoriesRecorded', 'patternsLearned', 'signalsProcessed']) {
+                if (!Number.isSafeInteger(merged[key]) || merged[key] < 0) {
+                    throw Object.assign(new Error('Learning stats counter overflow'), { code: 'EINVALIDSTATS' });
+                }
+            }
+            if (merged.lastAdaptation != null &&
+                (!Number.isFinite(merged.lastAdaptation) || merged.lastAdaptation < 0)) {
+                throw Object.assign(new Error('Invalid merged learning stats timestamp'), { code: 'EINVALIDSTATS' });
+            }
+            const tmp = `${path}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(merged, null, 2), 'utf-8');
+            renameSync(tmp, path);
+            // Commit local state before release: a failed release must not replay it.
+            globalStats = merged;
+            pendingDelta = { trajectoriesRecorded: 0, patternsLearned: 0, signalsProcessed: 0 };
+            persistedStatsLoaded = true;
+        });
     }
-    catch {
-        // Ignore save errors
+    catch (error) {
+        const { code = 'UNKNOWN', path = statsPath || 'neural stats directory' } = error;
+        // Do not print file contents, which may be malformed or user-controlled.
+        console.warn(`[intelligence] Could not persist learning stats at ${path} (${code}); pending increments retained`);
     }
 }
 /**
@@ -679,7 +786,7 @@ function savePersistedStats() {
 let signalsSinceLastSave = 0;
 const SIGNAL_PERSIST_EVERY = 16;
 export function recordSignalProcessed() {
-    globalStats.signalsProcessed = (globalStats.signalsProcessed ?? 0) + 1;
+    bumpStat('signalsProcessed');
     signalsSinceLastSave++;
     if (signalsSinceLastSave >= SIGNAL_PERSIST_EVERY) {
         savePersistedStats();
@@ -881,7 +988,7 @@ export async function recordStep(step) {
             await sonaCoordinator.distillLearning(reasoningBank);
             globalStats.lastAdaptation = Date.now();
         }
-        globalStats.trajectoriesRecorded++;
+        bumpStat('trajectoriesRecorded');
         savePersistedStats();
         return true;
     }
@@ -928,7 +1035,7 @@ export async function recordTrajectory(steps, verdict) {
             if (verdict === 'success') {
                 for (const step of enrichedSteps) {
                     if (step.embedding && step.embedding.length > 0) {
-                        reasoningBank.store({
+                        const added = reasoningBank.store({
                             id: `pattern-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
                             type: step.type,
                             content: step.content,
@@ -937,7 +1044,11 @@ export async function recordTrajectory(steps, verdict) {
                             metadata: step.metadata || {},
                             createdAt: Date.now(),
                         });
-                        globalStats.patternsLearned++;
+                        // #3979 item 4: count only patterns that were actually added. A step
+                        // whose content already exists is merged into that pattern, so the
+                        // counter no longer climbs once per successful step.
+                        if (added)
+                            bumpStat('patternsLearned');
                     }
                 }
             }
@@ -949,20 +1060,22 @@ export async function recordTrajectory(steps, verdict) {
                 const avgQuality = verdict === 'success' ? 1.0 : verdict === 'partial' ? 0.5 : 0.0;
                 ruvllmCoord.recordTrajectory({
                     steps: enrichedSteps.map(s => ({
-                        state: s.content,
-                        action: s.type,
-                        reward: avgQuality,
-                        embedding: s.embedding || []
+                        type: ['query', 'route', 'generate', 'memory', 'feedback'].includes(s.type)
+                            ? s.type : 'generate',
+                        input: s.content,
+                        output: '',
+                        durationMs: 0,
+                        confidence: avgQuality
                     })),
                     totalReward: avgQuality,
-                    success: verdict === 'success'
+                    outcome: verdict
                 });
             }
             catch {
                 // ruvllm recording failed silently
             }
         }
-        globalStats.trajectoriesRecorded++;
+        bumpStat('trajectoriesRecorded');
         globalStats.lastAdaptation = Date.now();
         savePersistedStats();
         return true;
@@ -1034,6 +1147,12 @@ export function getIntelligenceStats() {
     if (!ruvllmLoaded) {
         loadRuvllmCoordinatorSync();
     }
+    // A read-only status process (ruvllm_status, `neural status`, a fresh MCP
+    // server) has never run initializeIntelligence(); without this it reported
+    // 0 trajectories no matter what other processes had persisted.
+    if (!persistedStatsLoaded) {
+        loadPersistedStats();
+    }
     const ruvllmStats = ruvllmCoordinator?.stats?.() || null;
     // Fetch cross-module stats for unified reporting.
     //
@@ -1145,6 +1264,10 @@ export function clearIntelligence() {
         signalsProcessed: 0,
         lastAdaptation: null
     };
+    pendingDelta = { trajectoriesRecorded: 0, patternsLearned: 0, signalsProcessed: 0 };
+    // In-memory reset only: stay "loaded" so the next stats read does not
+    // immediately re-hydrate the counters this call just cleared.
+    persistedStatsLoaded = true;
 }
 /**
  * Benchmark SONA adaptation time

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

@@ -19,10 +19,11 @@
 import { AppendConditionFailed, assertAppendConditions, validateAppendConditions } from './append-conditions.js';
 import { liveMemoryRowSql } from './live-memory-row.js';
 import { resolveAgentdbBetterSqlite3 } from './shared-sqlite.js';
+import { DEFAULT_SEARCH_THRESHOLD } from './search-defaults.js';
 import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import { realpathSync } from 'node:fs';
+import { mkdirSync, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { validateFeedbackPatterns } from './feedback-patterns.js';
@@ -265,7 +266,13 @@ async function getRegistry(dbPath) {
                         return;
                     origLog.apply(console, args);
                 };
+                // #4132: better-sqlite3 cannot create a missing parent directory. In a
+                // fresh checkout or worktree `.swarm/` does not exist yet, so AgentDB
+                // failed to open, the degraded registry was cached for the server's
+                // lifetime and hierarchical memory silently ran volatile.
                 try {
+                    if (resolvedPath !== ':memory:')
+                        mkdirSync(path.dirname(resolvedPath), { recursive: true });
                     await registry.initialize({
                         // #2786: use agentdb-memory.db (plaintext) so native better-sqlite3 doesn't hit the encrypted memory.db.
                         dbPath: resolvedPath,
@@ -1299,7 +1306,7 @@ export async function bridgeSearchEntries(options) {
     if (!ctx)
         return null;
     try {
-        const { query: queryStr, namespace, limit = 10, threshold = 0.3, provenanceFilter } = options;
+        const { query: queryStr, namespace, limit = 10, threshold = DEFAULT_SEARCH_THRESHOLD, provenanceFilter } = options;
         const effectiveNamespace = namespace || 'all';
         const startTime = Date.now();
         // Generate query embedding — same agentdb-then-local chain as the write
@@ -1870,7 +1877,7 @@ export async function bridgeSearchBruteForceCosine(queryEmbedding, options, dbPa
         return null;
     try {
         const k = options?.k ?? 10;
-        const threshold = options?.threshold ?? 0.3;
+        const threshold = options?.threshold ?? DEFAULT_SEARCH_THRESHOLD;
         const nsFilter = options?.namespace && options.namespace !== 'all'
             ? `AND namespace = ?`
             : '';

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

@@ -1,5 +1,6 @@
 import { loadBetterSqlite3 } from './shared-sqlite.js';
 import { resolveMemoryRoot } from './memory-root.js';
+import { DEFAULT_SEARCH_THRESHOLD } from './search-defaults.js';
 import { liveMemoryRowSql } from './live-memory-row.js';
 import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
 import * as fs from 'fs';
@@ -2745,7 +2746,7 @@ export async function searchEntries(options) {
             return bridgeResult;
     }
     // Fallback: raw sql.js
-    const { query, namespace, limit = 10, threshold = 0.3, dbPath: customPath, provenanceFilter } = options;
+    const { query, namespace, limit = 10, threshold = DEFAULT_SEARCH_THRESHOLD, dbPath: customPath, provenanceFilter } = options;
     const effectiveNamespace = namespace || 'all';
     const swarmDir = getMemoryRoot();
     const dbPath = customPath ? path.resolve(customPath) : path.join(swarmDir, 'memory.db');

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

@@ -0,0 +1,54 @@
+/**
+ * Default relevance floor for memory search (#4129).
+ *
+ * The bundled 384-dim embedding model scores a correct paraphrase match at
+ * roughly 0.25-0.5 and unrelated text at 0.0-0.15, so the old 0.3 floor sent
+ * back an empty list for natural-language queries whose right answer was
+ * clearly the best match (0.28 in the report). 0.2 sits between the two
+ * populations. An explicit `threshold` always wins, including 0.
+ *
+ * #2558 constraint stays: the fused recall score of a full-coverage exact
+ * keyword hit with semantic cosine <= 0 tops out at 0.40, so this must stay
+ * well below 0.4.
+ */
+export declare const DEFAULT_SEARCH_THRESHOLD = 0.2;
+/** How many below-threshold matches an empty default search reports as hints. */
+export declare const NEAR_MISS_LIMIT = 3;
+interface NearMissSearch {
+    (req: {
+        query: string;
+        namespace?: string;
+        limit?: number;
+        threshold?: number;
+        provenanceFilter?: string[];
+        dbPath?: string;
+    }): Promise<{
+        success: boolean;
+        results?: Array<{
+            key: string;
+            namespace: string;
+            score: number;
+        }>;
+    }>;
+}
+/**
+ * When a search that used the DEFAULT threshold returns nothing, say what was
+ * close instead of leaving the caller to assume the store has no answer
+ * (#4129). One extra, cheap query at threshold 0; never throws; absent when
+ * nothing at all matched.
+ */
+export declare function nearMisses(search: NearMissSearch, req: {
+    query: string;
+    namespace?: string;
+    provenanceFilter?: string[];
+    dbPath?: string;
+}): Promise<{
+    nearMisses: Array<{
+        key: string;
+        namespace: string;
+        similarity: number;
+    }>;
+    hint: string;
+} | undefined>;
+export {};
+//# sourceMappingURL=search-defaults.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * Default relevance floor for memory search (#4129).
+ *
+ * The bundled 384-dim embedding model scores a correct paraphrase match at
+ * roughly 0.25-0.5 and unrelated text at 0.0-0.15, so the old 0.3 floor sent
+ * back an empty list for natural-language queries whose right answer was
+ * clearly the best match (0.28 in the report). 0.2 sits between the two
+ * populations. An explicit `threshold` always wins, including 0.
+ *
+ * #2558 constraint stays: the fused recall score of a full-coverage exact
+ * keyword hit with semantic cosine <= 0 tops out at 0.40, so this must stay
+ * well below 0.4.
+ */
+export const DEFAULT_SEARCH_THRESHOLD = 0.2;
+/** How many below-threshold matches an empty default search reports as hints. */
+export const NEAR_MISS_LIMIT = 3;
+/**
+ * When a search that used the DEFAULT threshold returns nothing, say what was
+ * close instead of leaving the caller to assume the store has no answer
+ * (#4129). One extra, cheap query at threshold 0; never throws; absent when
+ * nothing at all matched.
+ */
+export async function nearMisses(search, req) {
+    try {
+        const r = await search({ ...req, limit: NEAR_MISS_LIMIT, threshold: 0 });
+        if (!r?.success || !r.results?.length)
+            return undefined;
+        return {
+            nearMisses: r.results.map(e => ({ key: e.key, namespace: e.namespace, similarity: e.score })),
+            hint: `No result reached the default threshold (${DEFAULT_SEARCH_THRESHOLD}); the closest matches are in nearMisses. Pass threshold: 0 to include them in results.`,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=search-defaults.js.map