claude-flow 3.56.8 → 3.56.10

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

@@ -12,6 +12,7 @@
 import { validateText, validateIdentifier } from './validate-input.js';
 import { autoInstallPackage } from './auto-install.js';
 import { createRequire } from 'module';
+import { findKnownMiss, recordKnownMiss } from './aidefence-known-misses.js';
 // Create require for resolving module paths
 const require = createRequire(import.meta.url);
 // Lazy-loaded AIDefence instance
@@ -152,7 +153,8 @@ const aidefenceScanTool = {
                     piiPresent = !!defender.hasPII(input);
                 }
                 catch { /* hasPII unavailable */ }
-                const threatDetected = result.threat || piiPresent;
+                const knownMiss = findKnownMiss(input);
+                const threatDetected = result.threat || piiPresent || !!knownMiss;
                 wrapperStats.quickScanCalls++;
                 if (threatDetected)
                     wrapperStats.quickScanThreats++;
@@ -164,24 +166,29 @@ const aidefenceScanTool = {
                                 threatDetected,
                                 confidence: result.confidence,
                                 piiDetected: piiPresent,
-                                promptInjectionDetected: result.threat,
+                                promptInjectionDetected: result.threat || !!knownMiss,
+                                ...(knownMiss ? { knownMiss: { threatType: knownMiss.threatType, reportedAt: knownMiss.reportedAt } } : {}),
                                 mode: 'quick',
                             }, null, 2),
                         }],
                 };
             }
             const result = await defender.detect(input);
+            const knownMiss = findKnownMiss(input);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
-                            safe: result.safe,
-                            threats: result.threats.map(t => ({
-                                type: t.type,
-                                severity: t.severity,
-                                confidence: t.confidence,
-                                description: t.description,
-                            })),
+                            safe: result.safe && !knownMiss,
+                            threats: [
+                                ...result.threats.map(t => ({
+                                    type: t.type,
+                                    severity: t.severity,
+                                    confidence: t.confidence,
+                                    description: t.description,
+                                })),
+                                ...(knownMiss ? [{ type: knownMiss.threatType, severity: 'high', confidence: 1, description: 'Matches an input previously reported as a missed threat (aidefence_learn)' }] : []),
+                            ],
                             piiFound: result.piiFound,
                             detectionTimeMs: result.detectionTimeMs,
                         }, null, 2),
@@ -398,11 +405,33 @@ const aidefenceLearnTool = {
             const defender = await getAIDefence();
             // Re-detect to get result for learning
             const result = await defender.detect(input);
-            // Learn from detection
-            await defender.learnFromDetection(input, result, {
-                wasAccurate,
-                userVerdict: verdict,
-            });
+            // A false negative (wasAccurate=false, nothing detected) gives
+            // learnFromDetection() no threat to store, so record the miss itself.
+            const falseNegative = !wasAccurate && result.threats.length === 0;
+            const missType = threatType || 'prompt_injection';
+            let learned = result.threats.length;
+            let newlyRecorded = false;
+            if (falseNegative) {
+                newlyRecorded = recordKnownMiss(input, missType);
+                if (newlyRecorded) {
+                    const synthetic = {
+                        ...result,
+                        safe: false,
+                        threats: [{
+                                type: missType,
+                                severity: 'high',
+                                confidence: 1,
+                                pattern: 'user-reported-miss',
+                                description: verdict || 'Reported by user as a missed threat',
+                            }],
+                    };
+                    await defender.learnFromDetection(input, synthetic, { wasAccurate, userVerdict: verdict });
+                }
+                learned = 1;
+            }
+            else {
+                await defender.learnFromDetection(input, result, { wasAccurate, userVerdict: verdict });
+            }
             // Record mitigation if provided
             if (threatType && mitigationStrategy && mitigationSuccess !== undefined) {
                 await defender.recordMitigation(threatType, mitigationStrategy, mitigationSuccess);
@@ -412,7 +441,14 @@ const aidefenceLearnTool = {
                         type: 'text',
                         text: JSON.stringify({
                             success: true,
-                            message: 'Feedback recorded for pattern learning',
+                            message: falseNegative
+                                ? (newlyRecorded
+                                    ? 'Missed threat recorded: this exact input (normalised for case/whitespace) will now be flagged by aidefence_scan and aidefence_is_safe. Detection is pattern-based and does not generalise from it.'
+                                    : 'This input was already recorded as a missed threat')
+                                : (learned === 0
+                                    ? 'Feedback noted, but no threat was detected so no pattern was learned. To teach a missed threat, pass wasAccurate=false.'
+                                    : 'Feedback recorded for pattern learning'),
+                            learned,
                             learnedFrom: {
                                 input: input.slice(0, 50) + (input.length > 50 ? '...' : ''),
                                 wasAccurate,
@@ -468,7 +504,8 @@ const aidefenceIsSafeTool = {
                 piiPresent = !!defender.hasPII(input);
             }
             catch { /* hasPII unavailable */ }
-            const safe = promptSafe && !piiPresent;
+            const knownMiss = findKnownMiss(input);
+            const safe = promptSafe && !piiPresent && !knownMiss;
             wrapperStats.isSafeCalls++;
             if (!safe)
                 wrapperStats.isSafeUnsafeVerdicts++;
@@ -477,8 +514,9 @@ const aidefenceIsSafeTool = {
                         type: 'text',
                         text: JSON.stringify({
                             safe,
-                            promptSafe,
+                            promptSafe: promptSafe && !knownMiss,
                             piiPresent,
+                            ...(knownMiss ? { knownMiss: { threatType: knownMiss.threatType, reportedAt: knownMiss.reportedAt } } : {}),
                         }, null, 2),
                     }],
             };

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,12 @@
  *
  * @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';
 // ============================================================================
 // Persistence Configuration
 // ============================================================================
@@ -24,7 +25,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 +434,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 +457,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 +474,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 +488,7 @@ class LocalReasoningBank {
         this.patterns.set(pattern.id, stored);
         // Trigger persistence (debounced)
         this.saveToDisk();
+        return true;
     }
     /**
      * Find similar patterns by embedding.
@@ -629,43 +642,92 @@ let globalStats = {
     signalsProcessed: 0,
     lastAdaptation: null
 };
-// ============================================================================
-// Stats Persistence
-// ============================================================================
 /**
- * Load persisted stats from disk
+ * 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.
  */
-function loadPersistedStats() {
+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 {
         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;
-            }
-        }
+        if (!existsSync(path))
+            return null;
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        return data && typeof data === 'object' ? data : null;
     }
     catch {
-        // Ignore load errors, start fresh
+        return null;
     }
 }
+// ============================================================================
+// Stats Persistence
+// ============================================================================
+/**
+ * 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);
+}
 /**
- * Save stats to disk
+ * Save stats to disk: merge this process's unsaved deltas into whatever is
+ * currently on disk (read-merge-write, atomic rename), then adopt the merged
+ * totals locally so this process also sees other writers' progress.
  */
 function savePersistedStats() {
     try {
         ensureDataDir();
         const path = getStatsPath();
-        writeFileSync(path, JSON.stringify(globalStats, null, 2), 'utf-8');
+        const disk = readStatsFile();
+        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 };
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(merged, null, 2), 'utf-8');
+        renameSync(tmp, path);
+        globalStats = merged;
+        pendingDelta = { trajectoriesRecorded: 0, patternsLearned: 0, signalsProcessed: 0 };
+        persistedStatsLoaded = true;
     }
     catch {
-        // Ignore save errors
+        // Ignore save errors (deltas are retained for the next save)
     }
 }
 /**
@@ -679,7 +741,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 +943,7 @@ export async function recordStep(step) {
             await sonaCoordinator.distillLearning(reasoningBank);
             globalStats.lastAdaptation = Date.now();
         }
-        globalStats.trajectoriesRecorded++;
+        bumpStat('trajectoriesRecorded');
         savePersistedStats();
         return true;
     }
@@ -928,7 +990,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 +999,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');
                     }
                 }
             }
@@ -962,7 +1028,7 @@ export async function recordTrajectory(steps, verdict) {
                 // ruvllm recording failed silently
             }
         }
-        globalStats.trajectoriesRecorded++;
+        bumpStat('trajectoriesRecorded');
         globalStats.lastAdaptation = Date.now();
         savePersistedStats();
         return true;
@@ -1034,6 +1100,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 +1217,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