claude-flow 3.21.0 → 3.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.21.0",
+  "version": "3.21.1",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/commands/doctor.js

@@ -13,6 +13,7 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import { decodeKey, isEncryptionEnabled } from '../encryption/vault.js';
 import { isEncryptedBlob } from '../encryption/vault.js';
+import { resolveMemoryPackageFromProject, readMemoryPackageVersion, recordMemoryPackagePath, } from '../init/memory-package-resolver.js';
 // Promisified exec with proper shell and env inheritance for cross-platform support
 const execAsync = promisify(exec);
 /**
@@ -244,6 +245,37 @@ async function checkMemoryDatabase() {
     }
     return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
 }
+// #2545: Check that the self-learning bridge can actually load @claude-flow/memory
+// the SAME way the SessionStart auto-memory hook does. On the documented `npx ruflo`
+// path the package lands in the npx cache — unreachable from the project — so the
+// hook silently no-op'd with no signal anywhere. This surfaces it.
+async function checkLearningBridge() {
+    const cwd = process.cwd();
+    const hookPath = join(cwd, '.claude', 'helpers', 'auto-memory-hook.mjs');
+    // Only relevant once init has deployed the hook; otherwise stay quiet.
+    if (!existsSync(hookPath)) {
+        return {
+            name: 'Learning Bridge',
+            status: 'pass',
+            message: 'auto-memory hook not installed (run: npx ruflo@latest init)',
+        };
+    }
+    const distPath = resolveMemoryPackageFromProject(cwd);
+    if (distPath) {
+        const version = readMemoryPackageVersion(distPath);
+        return {
+            name: 'Learning Bridge',
+            status: 'pass',
+            message: `@claude-flow/memory resolvable${version ? ` (v${version})` : ''}`,
+        };
+    }
+    return {
+        name: 'Learning Bridge',
+        status: 'fail',
+        message: '@claude-flow/memory NOT resolvable — SessionStart self-learning imports are a silent no-op',
+        fix: 'npx ruflo@latest doctor --fix   (records resolver sidecar) — or: npm i -D @claude-flow/memory',
+    };
+}
 // Check API keys
 async function checkApiKeys() {
     const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];
@@ -1036,6 +1068,7 @@ export const doctorCommand = {
             checkStaleSettingsNpx, // #2448 — runaway `npx @latest` in statusLine/hooks
             checkDaemonStatus,
             checkMemoryDatabase,
+            checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
             checkApiKeys,
             checkMcpServers,
             checkAIDefence, // #1807
@@ -1057,6 +1090,8 @@ export const doctorCommand = {
             'stale-settings': checkStaleSettingsNpx, // #2448
             'daemon': checkDaemonStatus,
             'memory': checkMemoryDatabase,
+            'learning': checkLearningBridge, // #2545
+            'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,
             'git': checkGit,
             'mcp': checkMcpServers,
@@ -1107,6 +1142,27 @@ export const doctorCommand = {
             spinner.stop();
             output.writeln(output.error('Failed to run health checks'));
         }
+        // #2545: --fix / --install can actually repair the Learning Bridge by
+        // recording the resolver sidecar. When doctor runs via `npx ruflo`, the CLI
+        // CAN resolve its optional @claude-flow/memory dep (it is in the same npx
+        // cache), so writing the sidecar makes the SessionStart hook find it.
+        if ((showFix || autoInstall)) {
+            const lbResult = results.find(r => r.name === 'Learning Bridge');
+            if (lbResult && lbResult.status === 'fail') {
+                const record = recordMemoryPackagePath(process.cwd(), 'doctor');
+                if (record) {
+                    const newCheck = await checkLearningBridge();
+                    const idx = results.findIndex(r => r.name === 'Learning Bridge');
+                    if (idx !== -1)
+                        results[idx] = newCheck;
+                    const fixIdx = fixes.findIndex(f => f.startsWith('Learning Bridge:'));
+                    if (fixIdx !== -1 && newCheck.status === 'pass')
+                        fixes.splice(fixIdx, 1);
+                    output.writeln(output.success(`Repaired Learning Bridge — wrote .claude-flow/memory-package.json → ${record.distPath}`));
+                    output.writeln(formatCheck(newCheck));
+                }
+            }
+        }
         // Auto-install missing dependencies if requested
         if (autoInstall) {
             const claudeCodeResult = results.find(r => r.name === 'Claude Code CLI');

package/v3/@claude-flow/cli/dist/src/init/executor.js

@@ -16,6 +16,7 @@ import { generateMCPJson } from './mcp-generator.js';
 import { generateStatuslineScript } from './statusline-generator.js';
 import { generatePreCommitHook, generatePostCommitHook, generateSessionManager, generateAgentRouter, generateMemoryHelper, generateHookHandler, generateIntelligenceStub, generateAutoMemoryHook, generateRufloHookCjs, } from './helpers-generator.js';
 import { generateClaudeMd } from './claudemd-generator.js';
+import { recordMemoryPackagePath } from './memory-package-resolver.js';
 /**
  * Skills to copy based on configuration
  */
@@ -196,6 +197,16 @@ export async function executeInit(options) {
         // Generate helpers
         if (options.components.helpers) {
             await writeHelpers(targetDir, options, result);
+            // #2545: The auto-memory hook needs @claude-flow/memory, which is an
+            // optionalDependency of the CLI and lands in the npx cache — unreachable
+            // by a node_modules walk-up from the user's project. Resolve it from the
+            // CLI's own context now (where it IS present) and record the absolute
+            // path in a machine-local sidecar the hook reads first. Best-effort:
+            // when the optional dep is absent the hook fails loud and doctor flags it.
+            const memRecord = recordMemoryPackagePath(targetDir, 'init');
+            if (memRecord) {
+                result.created.files.push('.claude-flow/memory-package.json');
+            }
         }
         // Generate statusline
         if (options.components.statusline) {
@@ -472,6 +483,12 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
+        // #2545: (re)record the resolved @claude-flow/memory path so the auto-memory
+        // hook can find it on the npx install path. Best-effort — see executeInit.
+        const memRecord = recordMemoryPackagePath(targetDir, 'upgrade');
+        if (memRecord) {
+            result.updated.push('.claude-flow/memory-package.json');
+        }
         // 1. ALWAYS update statusline helper (force overwrite)
         const statuslinePath = path.join(targetDir, '.claude', 'helpers', 'statusline.cjs');
         // Use default options with statusline config

package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js

@@ -863,13 +863,37 @@ const DATA_DIR = join(PROJECT_ROOT, '.claude-flow', 'data');
 const STORE_PATH = join(DATA_DIR, 'auto-memory-store.json');
 
 const DIM = '\\x1b[2m';
+const YELLOW = '\\x1b[0;33m';
 const RESET = '\\x1b[0m';
 const dim = (msg) => console.log(\`  \${DIM}\${msg}\${RESET}\`);
 
+// #2545: fail LOUD instead of a silent dim skip when @claude-flow/memory is
+// unresolvable — self-learning imports are a no-op and the user must be told.
+function warnMemoryUnavailable() {
+  const l1 = \`[AutoMemory] @claude-flow/memory not resolvable from \${PROJECT_ROOT} — self-learning imports are DISABLED.\`;
+  const l2 = '             Fix: npm i -D @claude-flow/memory   (or re-run: npx ruflo@latest init, then npx ruflo@latest doctor --fix)';
+  console.log(\`\${YELLOW}\${l1}\${RESET}\`);
+  console.log(\`\${YELLOW}\${l2}\${RESET}\`);
+  process.stderr.write(\`\${l1}\\n\${l2}\\n\`);
+}
+
 // Ensure data dir
 if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
 
 async function loadMemoryPackage() {
+  // Strategy 0 (#2545): sidecar recorded by \`init\` / \`doctor --fix\`. On the npx
+  // path @claude-flow/memory lands in the npx cache (unreachable by walk-up), so
+  // init records its absolute path here — the only strategy that works there.
+  try {
+    const sidecar = join(PROJECT_ROOT, '.claude-flow', 'memory-package.json');
+    if (existsSync(sidecar)) {
+      const rec = JSON.parse(readFileSync(sidecar, 'utf-8'));
+      if (rec && rec.distPath && existsSync(rec.distPath)) {
+        return await import(\`file://\${rec.distPath}\`);
+      }
+    }
+  } catch { /* fall through */ }
+
   // Strategy 1: Use createRequire for CJS-style resolution (handles nested node_modules
   // when installed as a transitive dependency via npx ruflo / npx claude-flow)
   try {
@@ -899,7 +923,7 @@ async function doImport() {
   const memPkg = await loadMemoryPackage();
 
   if (!memPkg || !memPkg.AutoMemoryBridge) {
-    dim('Memory package not available — auto memory import skipped (non-critical)');
+    warnMemoryUnavailable();
     return;
   }
 
@@ -916,7 +940,7 @@ async function doSync() {
   const memPkg = await loadMemoryPackage();
 
   if (!memPkg || !memPkg.AutoMemoryBridge) {
-    dim('Memory package not available — sync skipped (non-critical)');
+    warnMemoryUnavailable();
     return;
   }
 

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

@@ -0,0 +1,53 @@
+/**
+ * Memory Package Resolver (#2545)
+ *
+ * `@claude-flow/memory` is an *optionalDependency* of `@claude-flow/cli`. On the
+ * documented `npx ruflo` install path it lands in the npx cache
+ * (`~/.npm/_npx/<hash>/node_modules`), which is NOT on the node_modules walk-up
+ * path from the user's project. The SessionStart auto-memory hook therefore
+ * could never resolve it and self-learning silently no-op'd.
+ *
+ * At init time, however, the CLI *can* resolve the package from its own module
+ * context (it is installed alongside the CLI in that same npx cache). We resolve
+ * it once and record the absolute path in a machine-local project sidecar
+ * (`.claude-flow/memory-package.json`). The hook reads this sidecar first, so it
+ * reuses the copy npx already downloaded — no second install, no vendoring.
+ *
+ * This module is deliberately dependency-free and best-effort: nothing here ever
+ * throws into the init/doctor flow.
+ */
+export declare const MEMORY_PACKAGE = "@claude-flow/memory";
+/** Project-relative path of the resolver sidecar written by init / doctor --fix. */
+export declare const MEMORY_SIDECAR_REL: string;
+export interface MemoryPackageRecord {
+    /** Absolute path to the package's main entry (dist/index.js). */
+    distPath: string;
+    /** Resolved package version, if readable. */
+    version: string | null;
+    /** What produced this record ("init" | "doctor" | "upgrade"). */
+    resolvedBy: string;
+    /** ISO timestamp of resolution. */
+    resolvedAt: string;
+}
+/**
+ * Resolve `@claude-flow/memory`'s main entry from the CLI's own module context.
+ * Returns the absolute dist path, or null when the optional dependency is absent
+ * (e.g. installed with `--omit=optional`).
+ */
+export declare function resolveMemoryPackageFromCli(): string | null;
+/**
+ * Resolve `@claude-flow/memory` the same way the runtime hook does, from a target
+ * project directory: sidecar → project package.json → node_modules walk-up.
+ * Used by `doctor` so its verdict matches what the hook will actually experience.
+ */
+export declare function resolveMemoryPackageFromProject(targetDir: string): string | null;
+/** Read the version of the resolved memory package (dist/index.js → ../package.json). */
+export declare function readMemoryPackageVersion(distPath: string): string | null;
+/**
+ * Best-effort: resolve `@claude-flow/memory` from the CLI and record its path in
+ * the project sidecar so the runtime hook can find it on the npx install path.
+ * Returns the written record, or null when the package is not resolvable from the
+ * CLI (in which case the hook fails loud and `doctor` flags it).
+ */
+export declare function recordMemoryPackagePath(targetDir: string, resolvedBy?: string): MemoryPackageRecord | null;
+//# sourceMappingURL=memory-package-resolver.d.ts.map

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

@@ -0,0 +1,118 @@
+/**
+ * Memory Package Resolver (#2545)
+ *
+ * `@claude-flow/memory` is an *optionalDependency* of `@claude-flow/cli`. On the
+ * documented `npx ruflo` install path it lands in the npx cache
+ * (`~/.npm/_npx/<hash>/node_modules`), which is NOT on the node_modules walk-up
+ * path from the user's project. The SessionStart auto-memory hook therefore
+ * could never resolve it and self-learning silently no-op'd.
+ *
+ * At init time, however, the CLI *can* resolve the package from its own module
+ * context (it is installed alongside the CLI in that same npx cache). We resolve
+ * it once and record the absolute path in a machine-local project sidecar
+ * (`.claude-flow/memory-package.json`). The hook reads this sidecar first, so it
+ * reuses the copy npx already downloaded — no second install, no vendoring.
+ *
+ * This module is deliberately dependency-free and best-effort: nothing here ever
+ * throws into the init/doctor flow.
+ */
+import { createRequire } from 'module';
+import * as fs from 'fs';
+import * as path from 'path';
+export const MEMORY_PACKAGE = '@claude-flow/memory';
+/** Project-relative path of the resolver sidecar written by init / doctor --fix. */
+export const MEMORY_SIDECAR_REL = path.join('.claude-flow', 'memory-package.json');
+/**
+ * Resolve `@claude-flow/memory`'s main entry from the CLI's own module context.
+ * Returns the absolute dist path, or null when the optional dependency is absent
+ * (e.g. installed with `--omit=optional`).
+ */
+export function resolveMemoryPackageFromCli() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require.resolve(MEMORY_PACKAGE);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve `@claude-flow/memory` the same way the runtime hook does, from a target
+ * project directory: sidecar → project package.json → node_modules walk-up.
+ * Used by `doctor` so its verdict matches what the hook will actually experience.
+ */
+export function resolveMemoryPackageFromProject(targetDir) {
+    // 1. Sidecar written by a previous init / doctor --fix
+    try {
+        const sidecar = path.join(targetDir, MEMORY_SIDECAR_REL);
+        if (fs.existsSync(sidecar)) {
+            const rec = JSON.parse(fs.readFileSync(sidecar, 'utf-8'));
+            if (rec?.distPath && fs.existsSync(rec.distPath))
+                return rec.distPath;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // 2. createRequire from the project's package.json (direct/transitive dep)
+    try {
+        const require = createRequire(path.join(targetDir, 'package.json'));
+        return require.resolve(MEMORY_PACKAGE);
+    }
+    catch {
+        /* fall through */
+    }
+    // 3. node_modules walk-up from the project root
+    let dir = path.resolve(targetDir);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const candidate = path.join(dir, 'node_modules', '@claude-flow', 'memory', 'dist', 'index.js');
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Read the version of the resolved memory package (dist/index.js → ../package.json). */
+export function readMemoryPackageVersion(distPath) {
+    try {
+        const pkgJson = path.resolve(path.dirname(distPath), '..', 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            const parsed = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+            return parsed.version ?? null;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+/**
+ * Best-effort: resolve `@claude-flow/memory` from the CLI and record its path in
+ * the project sidecar so the runtime hook can find it on the npx install path.
+ * Returns the written record, or null when the package is not resolvable from the
+ * CLI (in which case the hook fails loud and `doctor` flags it).
+ */
+export function recordMemoryPackagePath(targetDir, resolvedBy = 'init') {
+    const distPath = resolveMemoryPackageFromCli();
+    if (!distPath)
+        return null;
+    const record = {
+        distPath,
+        version: readMemoryPackageVersion(distPath),
+        resolvedBy,
+        resolvedAt: new Date().toISOString(),
+    };
+    try {
+        fs.mkdirSync(path.join(targetDir, '.claude-flow'), { recursive: true });
+        fs.writeFileSync(path.join(targetDir, MEMORY_SIDECAR_REL), JSON.stringify(record, null, 2), 'utf-8');
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=memory-package-resolver.js.map

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

@@ -680,6 +680,31 @@ export async function bridgeStoreEntry(options) {
         catch { /* vector_indexes may not exist on legacy DBs — fall through */ }
         const stmt = ctx.db.prepare(insertSql);
         stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', now, now, ttl ? now + (ttl * 1000) : null);
+        // #2558: keep `vector_indexes.total_vectors` accurate so status/tooling
+        // stop reporting "HNSW index: 0 vectors" while embedded entries exist.
+        try {
+            ctx.db
+                .prepare(`UPDATE vector_indexes SET
+             total_vectors = (SELECT COUNT(*) FROM memory_entries
+                              WHERE namespace = ? AND embedding IS NOT NULL),
+             updated_at = ?
+           WHERE name = ?`)
+                .run(namespace, now, namespace);
+        }
+        catch { /* vector_indexes may not exist on legacy DBs — non-fatal */ }
+        // #2558: better-sqlite3 opens the DB in WAL mode and, for the small write
+        // volumes typical of CLI usage, may never reach the auto-checkpoint
+        // threshold — leaving committed rows only in the -wal file. WAL-blind
+        // readers (the sql.js fallback search path; the statusline's read-only
+        // `sqlite3` vector count) then see a stale/empty main DB file and report
+        // "0 vectors" / empty search. A PASSIVE checkpoint flushes committed pages
+        // into the main file without blocking writers. Best-effort, never fatal.
+        try {
+            if (typeof ctx.db.pragma === 'function') {
+                ctx.db.pragma('wal_checkpoint(PASSIVE)');
+            }
+        }
+        catch { /* non-WAL, busy, or unsupported — non-fatal */ }
         // Phase 2: Write-through to TieredCache
         const safeNs = String(namespace).replace(/:/g, '_');
         const safeKey = String(key).replace(/:/g, '_');
@@ -770,17 +795,33 @@ export async function bridgeSearchEntries(options) {
                 // Normalize BM25 to 0-1 range (cap at 10 for normalization)
                 bm25ScoreVal = Math.min(bm25ScoreVal / 10, 1.0);
             }
-            // Reciprocal rank fusion: combine semantic and BM25
-            // Weight: 0.7 semantic + 0.3 BM25 when both embeddings present
-            // Fall back to BM25-only when either query or row lacks an embedding
-            const score = semanticScore > 0
-                ? (0.7 * semanticScore + 0.3 * bm25ScoreVal)
-                : bm25ScoreVal;
+            // #2558: keyword-coverage floor for the lexical signal.
+            // BM25's IDF collapses toward zero when a term appears in most/all
+            // documents (routine on small memory corpora), and the /10 normalization
+            // crushed exact-keyword hits well below the default 0.3 threshold — so
+            // `memory search` recalled NOTHING even when the content literally
+            // contained the query term (issue #2558: "keyword recall random"). The
+            // pre-BM25 fallback guaranteed keyword recall via matchCount/words*0.5;
+            // this restores that guarantee. `coverage` is the fraction of query
+            // terms present in the document — a full-coverage hit must always be
+            // recallable regardless of IDF.
+            const contentLower = String(row.content || '').toLowerCase();
+            const matchedTerms = queryTerms.filter(t => contentLower.includes(t)).length;
+            const coverage = queryTerms.length > 0 ? matchedTerms / queryTerms.length : 0;
+            const lexicalScore = Math.max(bm25ScoreVal, coverage);
+            // Recall-friendly fusion: a strong semantic OR lexical signal alone must
+            // clear the threshold. `blended` (0.6 semantic + 0.4 lexical) drives
+            // ranking; taking max() with the raw semantic score means (a) a genuinely
+            // similar entry is never dropped just because it lacks the query's exact
+            // words, and (b) a full-coverage keyword hit (lexical=1 → blended≥0.4) is
+            // never dropped just because its embedding cosine is low or negative.
+            const blended = 0.6 * Math.max(0, semanticScore) + 0.4 * lexicalScore;
+            const score = Math.max(blended, semanticScore);
             if (score >= threshold) {
                 // Phase 4: ExplainableRecall provenance
                 const provenance = queryEmbedding
-                    ? `semantic:${semanticScore.toFixed(3)}+bm25:${bm25ScoreVal.toFixed(3)}`
-                    : `bm25:${bm25ScoreVal.toFixed(3)}`;
+                    ? `semantic:${semanticScore.toFixed(3)}+lexical:${lexicalScore.toFixed(3)}`
+                    : `lexical:${lexicalScore.toFixed(3)}`;
                 results.push({
                     id: String(row.id).substring(0, 12),
                     key: row.key || String(row.id).substring(0, 15),

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.21.0",
+  "version": "3.21.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",