@claude-flow/cli 3.56.8 → 3.56.10

package/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/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/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/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/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

package/dist/src/memory/sona-optimizer.d.ts

@@ -93,6 +93,8 @@ export interface SONAStats {
         agents: number;
     } | 'unavailable';
 }
+/** The routing gate in getRoutingSuggestion: confidence x matchRatio must reach this for a learned pattern to be used. */
+export declare const SONA_ROUTING_GATE = 0.6;
 /** Agent roles supported by the SONA routing optimizer. */
 export declare function isSupportedSonaAgent(agent: string): boolean;
 /**
@@ -101,6 +103,17 @@ export declare function isSupportedSonaAgent(agent: string): boolean;
  * Learns from past task outcomes to improve future routing decisions.
  * Integrates with Q-learning router for hybrid routing strategy.
  */
+/**
+ * How close a pattern's confidence is to the routing gate. `successesNeeded`
+ * assumes a perfect keyword match (matchRatio 1) and the 0.1 success increment;
+ * a partial match needs more.
+ */
+export declare function routingGateStatus(confidence: number): {
+    threshold: number;
+    confidence: number;
+    reached: boolean;
+    successesNeeded: number;
+};
 export declare class SONAOptimizer {
     private patterns;
     private trajectoriesProcessed;
@@ -140,6 +153,15 @@ export declare class SONAOptimizer {
         patternKey: string;
         confidence: number;
         keywordsExtracted: string[];
+        /** True when this trajectory reinforced an existing near-identical pattern instead of creating a new one (#4134). */
+        reinforcedNeighbour?: boolean;
+        /** How far the pattern is from influencing routing, so a user can see learning has not kicked in yet (#4134). */
+        routingGate?: {
+            threshold: number;
+            confidence: number;
+            reached: boolean;
+            successesNeeded: number;
+        };
     };
     /**
      * Get routing suggestion based on learned patterns.
@@ -202,6 +224,12 @@ export declare class SONAOptimizer {
      * Create a unique pattern key from keywords and agent
      */
     private createPatternKey;
+    /**
+     * The key of the existing pattern for `agent` whose keyword set overlaps
+     * `keywords` the most, if that overlap (Jaccard) reaches NEIGHBOUR_MIN_JACCARD.
+     * Ties go to the more confident pattern. Linear in the pattern count (<= 1000).
+     */
+    private findNeighbourPattern;
     /**
      * Find the best matching pattern for given keywords
      */

package/dist/src/memory/sona-optimizer.js

@@ -26,6 +26,10 @@ const CONFIDENCE_INCREMENT = 0.1;
 const CONFIDENCE_DECREMENT = 0.15;
 const DECAY_RATE = 0.01; // Per day
 const MAX_PATTERNS = 1000;
+/** #4134: a trajectory reinforces an existing pattern of the same agent whose keyword set overlaps at least this much (Jaccard). */
+const NEIGHBOUR_MIN_JACCARD = 0.6;
+/** The routing gate in getRoutingSuggestion: confidence x matchRatio must reach this for a learned pattern to be used. */
+export const SONA_ROUTING_GATE = 0.6;
 // ============================================================================
 // Contrastive Trainer (lazy-loaded from @ruvector/ruvllm)
 // ============================================================================
@@ -119,6 +123,18 @@ const KEYWORD_CATEGORIES = {
  * Learns from past task outcomes to improve future routing decisions.
  * Integrates with Q-learning router for hybrid routing strategy.
  */
+/**
+ * How close a pattern's confidence is to the routing gate. `successesNeeded`
+ * assumes a perfect keyword match (matchRatio 1) and the 0.1 success increment;
+ * a partial match needs more.
+ */
+export function routingGateStatus(confidence) {
+    const reached = confidence >= SONA_ROUTING_GATE;
+    const successesNeeded = reached || confidence >= MAX_CONFIDENCE
+        ? 0
+        : Math.ceil(Math.log((1 - SONA_ROUTING_GATE) / (1 - confidence)) / Math.log(1 - CONFIDENCE_INCREMENT));
+    return { threshold: SONA_ROUTING_GATE, confidence, reached, successesNeeded };
+}
 export class SONAOptimizer {
     patterns = new Map();
     trajectoriesProcessed = 0;
@@ -210,7 +226,18 @@ export class SONAOptimizer {
             };
         }
         // Create pattern key from sorted keywords
-        const patternKey = this.createPatternKey(keywords, agent);
+        let patternKey = this.createPatternKey(keywords, agent);
+        // #4134: near-identical tasks ("Verify the X plugin ..." / "Verify the Y plugin ...")
+        // used to create a separate pattern each at confidence 0.5, so none ever reached
+        // the routing gate. Reinforce the closest existing pattern of the same agent instead.
+        let reinforcedNeighbour = false;
+        if (!this.patterns.has(patternKey)) {
+            const neighbour = this.findNeighbourPattern(keywords, agent);
+            if (neighbour) {
+                patternKey = neighbour;
+                reinforcedNeighbour = true;
+            }
+        }
         // Get or create pattern
         let pattern = this.patterns.get(patternKey);
         if (!pattern) {
@@ -264,6 +291,8 @@ export class SONAOptimizer {
             patternKey,
             confidence: pattern.confidence,
             keywordsExtracted: keywords,
+            reinforcedNeighbour,
+            routingGate: routingGateStatus(pattern.confidence),
         };
     }
     /**
@@ -305,7 +334,7 @@ export class SONAOptimizer {
         const keywords = this.extractKeywords(task);
         // Priority 2: Try SONA learned pattern matching
         const sonaResult = this.findBestPatternMatch(keywords);
-        if (sonaResult && sonaResult.confidence >= 0.6) {
+        if (sonaResult && sonaResult.confidence >= SONA_ROUTING_GATE) {
             return {
                 agent: sonaResult.agent,
                 confidence: sonaResult.confidence,
@@ -532,6 +561,34 @@ export class SONAOptimizer {
         const sortedKeywords = [...keywords].sort();
         return `${agent}:${sortedKeywords.join('+')}`;
     }
+    /**
+     * The key of the existing pattern for `agent` whose keyword set overlaps
+     * `keywords` the most, if that overlap (Jaccard) reaches NEIGHBOUR_MIN_JACCARD.
+     * Ties go to the more confident pattern. Linear in the pattern count (<= 1000).
+     */
+    findNeighbourPattern(keywords, agent) {
+        const wanted = new Set(keywords);
+        let bestKey = null;
+        let bestJaccard = 0;
+        let bestConfidence = -1;
+        for (const [key, pattern] of this.patterns) {
+            if (pattern.agent !== agent)
+                continue;
+            let shared = 0;
+            for (const k of pattern.keywords)
+                if (wanted.has(k))
+                    shared++;
+            const union = wanted.size + pattern.keywords.length - shared;
+            const jaccard = union === 0 ? 0 : shared / union;
+            if (jaccard >= NEIGHBOUR_MIN_JACCARD &&
+                (jaccard > bestJaccard || (jaccard === bestJaccard && pattern.confidence > bestConfidence))) {
+                bestKey = key;
+                bestJaccard = jaccard;
+                bestConfidence = pattern.confidence;
+            }
+        }
+        return bestKey;
+    }
     /**
      * Find the best matching pattern for given keywords
      */