claude-flow 3.21.0 → 3.22.0

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

@@ -15,7 +15,9 @@ import { generateSettingsJson, generateSettings } from './settings-generator.js'
 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 { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js';
 import { generateClaudeMd } from './claudemd-generator.js';
+import { recordMemoryPackagePath } from './memory-package-resolver.js';
 /**
  * Skills to copy based on configuration
  */
@@ -196,6 +198,29 @@ 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');
+            }
+            // #2568-followup: if this project already has a memory DB that predates
+            // the `vector_indexes` table (older CLI / agentdb-written), self-heal it
+            // so the statusline vector count + namespace routing work. Best-effort,
+            // dynamically imported so a WASM-only host without better-sqlite3 just
+            // skips it. Fresh projects have no DB yet — this is a no-op there.
+            try {
+                const memDbPath = path.join(targetDir, '.swarm', 'memory.db');
+                if (fs.existsSync(memDbPath)) {
+                    const { repairVectorIndexes } = await import('../memory/memory-initializer.js');
+                    await repairVectorIndexes(memDbPath, { autoRecover: true });
+                }
+            }
+            catch { /* best-effort — never block init on memory repair */ }
         }
         // Generate statusline
         if (options.components.statusline) {
@@ -472,6 +497,18 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
                 catch { }
             }
         }
+        // Stamp the installed version so the startup auto-refresh treats these as
+        // current (no redundant re-copy on the next command).
+        try {
+            fs.writeFileSync(path.join(targetDir, '.claude', 'helpers', HELPERS_STAMP_FILE), getInstalledCliVersion(), 'utf-8');
+        }
+        catch { /* non-fatal */ }
+        // #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/helper-refresh.d.ts

@@ -0,0 +1,19 @@
+export declare const HELPERS_STAMP_FILE = ".helpers-version";
+/** ruflo-owned helpers that carry hook logic and must track the package version. */
+export declare const CRITICAL_HELPERS: string[];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export declare function getInstalledCliVersion(): string;
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ */
+export declare function autoRefreshHelpersIfStale(cwd: string): Promise<{
+    refreshed: boolean;
+    from?: string;
+    to?: string;
+    blocked?: string;
+}>;
+//# sourceMappingURL=helper-refresh.d.ts.map

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

@@ -0,0 +1,175 @@
+/**
+ * Version-stamped critical-helper auto-refresh.
+ *
+ * The Claude Code hooks run the PROJECT-LOCAL `.claude/helpers/*.cjs` copies,
+ * not the installed npm package — so `npx ruflo@latest` does NOT update them,
+ * and users don't know to re-run `init`. This module stamps the helpers with
+ * the installed CLI version and, on the next CLI command, silently re-copies
+ * them when the stamp is stale. Hook fixes (e.g. the ADR-174 failure-capture
+ * change) then propagate to every user on their next `ruflo` command with zero
+ * action required.
+ *
+ * This file is intentionally LIGHTWEIGHT — it is imported on every CLI startup,
+ * so it depends only on `fs`/`path`/`module` at load time and lazily imports the
+ * heavy generators only on the rare fallback path (source dir unresolvable).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const HELPERS_STAMP_FILE = '.helpers-version';
+/** ruflo-owned helpers that carry hook logic and must track the package version. */
+export const CRITICAL_HELPERS = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export function getInstalledCliVersion() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(esmRequire.resolve('@claude-flow/cli/package.json'), 'utf-8'));
+        return String(pkg.version || '0.0.0');
+    }
+    catch {
+        // dist/src/init → package root
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+            return String(pkg.version || '0.0.0');
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
+function findPackageHelpersDir() {
+    const candidates = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = path.dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
+    }
+    catch { /* not resolvable */ }
+    candidates.push(path.resolve(__dirname, '..', '..', '..', '.claude', 'helpers'));
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
+            return c;
+    }
+    return null;
+}
+/**
+ * Re-copy the critical helpers into `helpersDir` and stamp `version`.
+ *
+ * SECURITY (fail-closed): when copying from the installed package, every source
+ * helper is verified against ruflo's Ed25519-signed manifest FIRST — nothing is
+ * copied unless the manifest signature is valid AND each helper's SHA-256
+ * matches. A tampered helper or manifest (e.g. a sibling package's postinstall
+ * overwriting on-disk hook code) is REFUSED, not propagated. The generator
+ * fallback needs no manifest — that content comes from the CLI's own compiled
+ * code, which is already the trust root.
+ */
+async function writeCriticalHelpers(helpersDir, version) {
+    const source = findPackageHelpersDir();
+    if (source) {
+        // 1. Verify the signed manifest against the baked public key.
+        let trusted = null;
+        try {
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'));
+        }
+        catch {
+            trusted = null;
+        }
+        if (!trusted)
+            return { wrote: false, blocked: 'signed helpers manifest missing or signature invalid' };
+        // 2. Verify EVERY source helper's hash before copying ANYTHING (atomic gate).
+        const toCopy = [];
+        for (const name of CRITICAL_HELPERS) {
+            const sp = path.join(source, name);
+            if (!fs.existsSync(sp))
+                continue;
+            const expected = trusted.files[name];
+            if (!expected || sha256Hex(fs.readFileSync(sp)) !== expected) {
+                return { wrote: false, blocked: `integrity check failed for ${name} — refusing to install` };
+            }
+            toCopy.push(name);
+        }
+        // 3. All verified — copy, plus the signed manifest itself as an audit trail.
+        let wrote = false;
+        for (const name of toCopy) {
+            const tp = path.join(helpersDir, name);
+            fs.copyFileSync(path.join(source, name), tp);
+            try {
+                fs.chmodSync(tp, '755');
+            }
+            catch { /* non-fatal */ }
+            wrote = true;
+        }
+        try {
+            fs.copyFileSync(path.join(source, HELPERS_MANIFEST_FILE), path.join(helpersDir, HELPERS_MANIFEST_FILE));
+        }
+        catch { /* non-fatal */ }
+        if (wrote) {
+            try {
+                fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+            }
+            catch { /* non-fatal */ }
+        }
+        return { wrote };
+    }
+    // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
+    // OWN compiled generators (the trust root; no external file to verify).
+    const gen = await import('./helpers-generator.js');
+    const files = {
+        'hook-handler.cjs': gen.generateHookHandler(),
+        'intelligence.cjs': gen.generateIntelligenceStub(),
+        'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+    };
+    let wrote = false;
+    for (const [name, content] of Object.entries(files)) {
+        const tp = path.join(helpersDir, name);
+        fs.writeFileSync(tp, content, 'utf-8');
+        try {
+            fs.chmodSync(tp, '755');
+        }
+        catch { /* non-fatal */ }
+        wrote = true;
+    }
+    if (wrote) {
+        try {
+            fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+        }
+        catch { /* non-fatal */ }
+    }
+    return { wrote };
+}
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ */
+export async function autoRefreshHelpersIfStale(cwd) {
+    try {
+        const helpersDir = path.join(cwd, '.claude', 'helpers');
+        if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
+            return { refreshed: false };
+        const version = getInstalledCliVersion();
+        let stamped = '';
+        try {
+            stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
+        }
+        catch { /* pre-feature: unstamped */ }
+        if (stamped === version)
+            return { refreshed: false }; // up to date — fast path
+        const res = await writeCriticalHelpers(helpersDir, version);
+        // A blocked refresh is a SECURITY signal (tampered source/manifest) — surface
+        // it, don't advance the stamp, and leave the project's existing helpers intact.
+        if (res.blocked)
+            return { refreshed: false, blocked: res.blocked };
+        return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+    }
+    catch {
+        return { refreshed: false };
+    }
+}
+//# sourceMappingURL=helper-refresh.js.map

package/v3/@claude-flow/cli/dist/src/init/helper-signing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export declare const RUFLO_HELPERS_PUBKEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=\n-----END PUBLIC KEY-----";
+export declare const HELPERS_MANIFEST_FILE = "helpers.manifest.json";
+export interface HelpersManifest {
+    version: string;
+    files: Record<string, string>;
+}
+export interface SignedHelpersManifest {
+    manifest: HelpersManifest;
+    signature: string;
+    algorithm: 'ed25519';
+}
+export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export declare function canonicalManifestBytes(m: HelpersManifest): Buffer;
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export declare function verifyHelpersManifest(signedJson: string, pubkeyPem?: string): HelpersManifest | null;
+//# sourceMappingURL=helper-signing.d.ts.map

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

@@ -0,0 +1,60 @@
+/**
+ * Ed25519 provenance for the auto-refreshed critical helpers (ADR-174 security).
+ *
+ * The helper auto-refresh copies auto-EXECUTING hook code (`hook-handler.cjs`
+ * etc.) from the installed package into a project. npm verifies the tarball at
+ * INSTALL time, but not the files on disk afterward — a sibling package's
+ * postinstall (or disk tampering) could overwrite them, and the refresh would
+ * faithfully propagate the tampered code. This gate closes that: every helper
+ * is verified against a ruflo-signed manifest before install, and a mismatch is
+ * REFUSED (fail-closed). The public key is baked in below; the private key is
+ * never in the repo (see scripts/sign-helpers.mjs).
+ *
+ * Native Node crypto (RFC 8032 Ed25519), zero external deps — same primitive as
+ * src/appliance/rvfa-signing.ts.
+ */
+import { createHash, verify as edVerify } from 'crypto';
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ */
+export const RUFLO_HELPERS_PUBKEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAhnFv74/CRcGWd0hL8zjyZ+52bIJ9SfcSgOutuKgo0Vg=
+-----END PUBLIC KEY-----`;
+export const HELPERS_MANIFEST_FILE = 'helpers.manifest.json';
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export function canonicalManifestBytes(m) {
+    const files = {};
+    for (const k of Object.keys(m.files).sort())
+        files[k] = m.files[k];
+    return Buffer.from(JSON.stringify({ version: m.version, files }), 'utf-8');
+}
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export function verifyHelpersManifest(signedJson, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    try {
+        const signed = JSON.parse(signedJson);
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        if (!signed.manifest.files || typeof signed.manifest.files !== 'object')
+            return null;
+        const bytes = canonicalManifestBytes(signed.manifest);
+        const ok = edVerify(null, bytes, pubkeyPem, Buffer.from(signed.signature, 'base64'));
+        return ok ? signed.manifest : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=helper-signing.js.map

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

@@ -4,6 +4,22 @@
  */
 import type { InitOptions } from './types.js';
 export declare const ATTRIBUTION_FOOTER = "\uD83E\uDD16 Generated with [RuFlo](https://github.com/ruvnet/ruflo)";
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export declare function isToolFailure(hookInput: unknown): boolean;
 /**
  * Generate pre-commit hook script
  */

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

@@ -9,6 +9,58 @@ import { generateStatuslineScript, generateStatuslineHook } from './statusline-g
 // PR body templates and release notes.  It is NEVER hard-wired into the
 // static command-file templates — those are user-owned content.
 export const ATTRIBUTION_FOOTER = '🤖 Generated with [RuFlo](https://github.com/ruvnet/ruflo)';
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export function isToolFailure(hookInput) {
+    if (!hookInput || typeof hookInput !== 'object')
+        return false;
+    const h = hookInput;
+    const tr = (h.tool_response ?? h.toolResponse ?? h.result);
+    if (tr == null)
+        return false;
+    if (typeof tr === 'string') {
+        return /\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\b/i.test(tr);
+    }
+    if (typeof tr === 'object') {
+        const o = tr;
+        if (o.is_error === true || o.isError === true || o.success === false || o.error != null)
+            return true;
+        // Bash tool: non-zero exit code is a failure.
+        const code = (o.exit_code ?? o.exitCode ?? o.code);
+        if (typeof code === 'number' && code !== 0)
+            return true;
+        // Nested content array (Claude tool result shape): {content:[...], is_error:true}
+        if (Array.isArray(o.content) && o.is_error === true)
+            return true;
+    }
+    return false;
+}
+// The exact predicate the generated hook inlines — kept in sync with
+// isToolFailure() above (mirrored, since the generated .cjs has no imports).
+const TOOL_FAILURE_EXPR = '(function(hi){' +
+    'if(!hi||typeof hi!=="object")return false;' +
+    'var tr=hi.tool_response!=null?hi.tool_response:(hi.toolResponse!=null?hi.toolResponse:hi.result);' +
+    'if(tr==null)return false;' +
+    'if(typeof tr==="string")return /\\b(error|failed|failure|exception|not found|no such|permission denied|traceback)\\b/i.test(tr);' +
+    'if(typeof tr==="object"){' +
+    'if(tr.is_error===true||tr.isError===true||tr.success===false||tr.error!=null)return true;' +
+    'var code=tr.exit_code!=null?tr.exit_code:(tr.exitCode!=null?tr.exitCode:tr.code);' +
+    'if(typeof code==="number"&&code!==0)return true;' +
+    'if(Array.isArray(tr.content)&&tr.is_error===true)return true;' +
+    '}return false;})(hookInput)';
 /**
  * Generate pre-commit hook script
  */
@@ -459,6 +511,9 @@ export function generateHookHandler() {
         '  // hook (#1944). Pull `.command` off whichever stdin shape Claude Code sent.',
         '  var toolInputObj = hookInput.toolInput || hookInput.tool_input || {};',
         "  var prompt = hookInput.prompt || hookInput.command || toolInputObj.command || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';",
+        '  // Capture FAILURES, not just successes, so the learning substrate has',
+        '  // negative examples (see ADR-174 / DB analysis). Mirrors isToolFailure().',
+        '  var toolFailed = ' + TOOL_FAILURE_EXPR + ';',
         '',
         'const handlers = {',
         "  'route': () => {",
@@ -503,10 +558,10 @@ export function generateHookHandler() {
         '    if (intelligence && intelligence.recordEdit) {',
         '      try {',
         "        var file = process.env.TOOL_INPUT_file_path || args[0] || '';",
-        '        intelligence.recordEdit(file);',
+        '        intelligence.recordEdit(file, !toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Edit recorded');",
+        "    console.log(toolFailed ? '[LEARN] Edit FAILURE recorded' : '[OK] Edit recorded');",
         '  },',
         '',
         "  'session-restore': () => {",
@@ -562,10 +617,10 @@ export function generateHookHandler() {
         "  'post-task': () => {",
         '    if (intelligence && intelligence.feedback) {',
         '      try {',
-        '        intelligence.feedback(true);',
+        '        intelligence.feedback(!toolFailed);',
         '      } catch (e) { /* non-fatal */ }',
         '    }',
-        "    console.log('[OK] Task completed');",
+        "    console.log(toolFailed ? '[LEARN] Task FAILURE recorded' : '[OK] Task completed');",
         '  },',
         '',
         "  'compact-manual': () => {",
@@ -809,10 +864,12 @@ export function generateIntelligenceStub() {
         '    return lines2.join("\\n");',
         '  },',
         '',
-        '  recordEdit: function(file) {',
+        '  recordEdit: function(file, success) {',
         '    if (!file) return;',
         '    ensureDir(DATA_DIR);',
-        '    var line = JSON.stringify({ type: "edit", file: file, timestamp: Date.now() }) + "\\n";',
+        '    // success defaults to true; an explicit false (failed edit) is recorded',
+        '    // so consolidation/distillation gets a negative example (ADR-174).',
+        '    var line = JSON.stringify({ type: "edit", file: file, success: success !== false, timestamp: Date.now() }) + "\\n";',
         '    fs.appendFileSync(PENDING_PATH, line, "utf-8");',
         '  },',
         '',
@@ -863,13 +920,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 +980,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 +997,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