claude-flow 3.21.0 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "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/daemon.js

@@ -14,6 +14,12 @@ const startCommand = {
     description: 'Start the worker daemon with all enabled background workers',
     options: [
         { name: 'workers', short: 'w', type: 'string', description: 'Comma-separated list of workers to enable (default: map,audit,optimize,consolidate,testgaps)' },
+        // ADR-174 M3: consolidate now runs a real memory-distillation pass
+        // (memory_entries -> episodes/reasoning_patterns/causal_edges) instead of
+        // a no-op stub. This opt-out skips just that pass for the life of this
+        // daemon process, without touching persisted worker-enabled state — for
+        // permanently disabling the worker use `daemon enable -w consolidate --disable`.
+        { name: 'no-distill', type: 'boolean', description: 'Disable the consolidate worker\'s memory-distillation pass (ADR-174)' },
         { name: 'quiet', short: 'Q', type: 'boolean', description: 'Suppress output' },
         { name: 'background', short: 'b', type: 'boolean', description: 'Run daemon in background (detached process)', default: true },
         { name: 'foreground', short: 'f', type: 'boolean', description: 'Run daemon in foreground (blocks terminal)' },
@@ -35,10 +41,19 @@ const startCommand = {
         { command: 'claude-flow daemon start --foreground', description: 'Start in foreground (blocks terminal)' },
         { command: 'claude-flow daemon start -w map,audit,optimize', description: 'Start with specific workers' },
         { command: 'claude-flow daemon start --headless --sandbox strict', description: 'Start with headless workers in strict sandbox' },
+        { command: 'claude-flow daemon start --no-distill', description: 'Start with the consolidate worker\'s distillation pass disabled' },
     ],
     action: async (ctx) => {
         const quiet = ctx.flags.quiet;
         const foreground = ctx.flags.foreground;
+        const noDistill = ctx.flags['no-distill'];
+        // ADR-174 M3: honored by WorkerDaemon's consolidate worker directly via
+        // process.env — set it now so the foreground path (which runs in this
+        // same process) picks it up too; the background path forwards it to the
+        // forked child's env explicitly (see startBackgroundDaemon below).
+        if (noDistill) {
+            process.env.RUFLO_DAEMON_NO_DISTILL = '1';
+        }
         // #1914: a forked daemon child receives --workspace <root>; the launcher
         // and interactive invocations have no flag and fall back to cwd.
         const projectRoot = resolveWorkspaceFlag(ctx.flags.workspace) ?? process.cwd();
@@ -208,6 +223,7 @@ const startCommand = {
                     headless: ctx.flags.headless,
                     sandbox: ctx.flags.sandbox,
                     ttl: rawTtl,
+                    noDistill,
                 });
             }
             finally {
@@ -404,7 +420,7 @@ export function extractWorkspaceFromDaemonLine(commandLine) {
     return ws.length > 0 ? ws : null;
 }
 async function startBackgroundDaemon(projectRoot, quiet, forwarded = {}) {
-    const { maxCpuLoad, minFreeMemory, workers, headless, sandbox, ttl } = forwarded;
+    const { maxCpuLoad, minFreeMemory, workers, headless, sandbox, ttl, noDistill } = forwarded;
     // Validate and resolve project root
     const resolvedRoot = resolve(projectRoot);
     validatePath(resolvedRoot, 'Project root');
@@ -493,6 +509,11 @@ async function startBackgroundDaemon(projectRoot, quiet, forwarded = {}) {
     if (typeof sandbox === 'string' && (sandbox === 'strict' || sandbox === 'permissive' || sandbox === 'disabled')) {
         forkArgs.push('--sandbox', sandbox);
     }
+    // ADR-174 M3: forward the distillation opt-out to the forked foreground
+    // child; its own `start` action sets RUFLO_DAEMON_NO_DISTILL from this flag.
+    if (noDistill === true) {
+        forkArgs.push('--no-distill');
+    }
     // #1914: stamp the workspace into argv (kept LAST) so the foreground daemon
     // process is self-identifying and `killStaleDaemons` only reaps daemons
     // belonging to this workspace. resolvedRoot was validatePath()'d above.
@@ -1352,7 +1373,7 @@ export const daemonCommand = {
             `${output.highlight('map')}         - Codebase mapping (5 min interval)`,
             `${output.highlight('audit')}       - Security analysis (10 min interval)`,
             `${output.highlight('optimize')}    - Performance optimization (15 min interval)`,
-            `${output.highlight('consolidate')} - Memory consolidation (30 min interval)`,
+            `${output.highlight('consolidate')} - Memory distillation: memory_entries -> episodes/reasoning_patterns/causal_edges (30 min interval, ADR-174; --no-distill to disable)`,
             `${output.highlight('testgaps')}    - Test coverage analysis (20 min interval)`,
             `${output.highlight('predict')}     - Predictive preloading (2 min, disabled by default)`,
             `${output.highlight('document')}    - Auto-documentation (60 min, disabled by default)`,

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/commands/memory-distill.d.ts

@@ -0,0 +1,27 @@
+import type { Command, CommandContext } from '../types.js';
+export interface DistillCliConfig {
+    dryRun: boolean;
+    namespaces?: string[];
+    batchSize: number;
+    dedupDistance: number;
+    maxEntries?: number;
+    sinceRowid?: number;
+    budgetUsd: number;
+    judge: 'structural' | 'fable';
+}
+type ResolveResult = {
+    ok: true;
+    config: DistillCliConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the effective distill config from: built-in defaults, an optional
+ * `--config <path>` JSON file, an `--aggressive`/`--conservative` preset, and
+ * finally explicit CLI flags (highest precedence).
+ */
+export declare function resolveDistillConfig(ctx: CommandContext): ResolveResult;
+export declare const distillCommand: Command;
+export default distillCommand;
+//# sourceMappingURL=memory-distill.d.ts.map

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

@@ -0,0 +1,374 @@
+/**
+ * V3 CLI `memory distill` Command Family (ADR-174 Milestone 2)
+ *
+ * CLI surface over the frozen M1 service (`../services/memory-distillation.js`
+ * — `runDistillation` / `defaultMemoryDbPath`). This file does not implement
+ * any distillation logic itself; it only resolves flags/config/presets into
+ * `DistillOptions`, calls the service, and formats the report.
+ *
+ *   memory distill run     — run (or dry-run) a distillation pass
+ *   memory distill status  — read-only report on the target tables + cursor
+ *   memory distill config  — print the effective resolved config as JSON
+ *
+ * Design notes:
+ *  - `--judge fable` requires `--budget-usd > 0` (ADR-172 cost-bounded advisor
+ *    gate). This is enforced here, client-side, as a fail-fast — the service
+ *    itself also refuses (`skipped: 'judge:fable requires ...'`) but failing
+ *    fast in the CLI gives a clearer, non-zero-exit error.
+ *  - `--aggressive` / `--conservative` are preset bundles (ADR-174 param
+ *    table). Precedence, low to high: built-in defaults < `--config` file <
+ *    preset < explicit `--batch-size`/`--dedup-distance` flags.
+ *  - `status` opens the DB read-only via the same "variable-specifier"
+ *    optional-import pattern used by `../memory/graph-edge-writer.ts` so the
+ *    TypeScript compiler never statically requires `better-sqlite3` types,
+ *    and degrades gracefully (no throw) when the DB, tables, or the native
+ *    module are absent.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { output } from '../output.js';
+import { runDistillation, defaultMemoryDbPath, } from '../services/memory-distillation.js';
+const DEFAULT_CONFIG = {
+    dryRun: false,
+    batchSize: 200,
+    dedupDistance: 0.2, // ADR-174 M4-tuned platform default (~37% fewer patterns, retrieval-neutral)
+    budgetUsd: 0,
+    judge: 'structural',
+};
+// ADR-174 preset bundles — distinct extremes around the 0.2 tuned default.
+const AGGRESSIVE_PRESET = { dedupDistance: 0.3, batchSize: 500 }; // more clustering → fewer, coarser patterns
+const CONSERVATIVE_PRESET = { dedupDistance: 0.1, batchSize: 100 }; // less clustering → more, granular patterns
+const DB_OPTION = {
+    name: 'db',
+    description: 'Path to the memory DB (default: cwd/.swarm/memory.db)',
+    type: 'string',
+};
+/**
+ * Resolve the effective distill config from: built-in defaults, an optional
+ * `--config <path>` JSON file, an `--aggressive`/`--conservative` preset, and
+ * finally explicit CLI flags (highest precedence).
+ */
+export function resolveDistillConfig(ctx) {
+    let cfg = { ...DEFAULT_CONFIG };
+    const configPath = ctx.flags.config;
+    if (configPath) {
+        try {
+            const raw = fs.readFileSync(path.resolve(configPath), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object') {
+                cfg = { ...cfg, ...parsed };
+            }
+        }
+        catch (error) {
+            return { ok: false, error: `Failed to load --config ${configPath}: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    const aggressive = ctx.flags.aggressive === true;
+    const conservative = ctx.flags.conservative === true;
+    if (aggressive && conservative) {
+        return { ok: false, error: '--aggressive and --conservative are mutually exclusive' };
+    }
+    if (aggressive)
+        cfg = { ...cfg, ...AGGRESSIVE_PRESET };
+    if (conservative)
+        cfg = { ...cfg, ...CONSERVATIVE_PRESET };
+    // Explicit CLI flags win over the config file and presets.
+    if (ctx.flags.dryRun === true)
+        cfg.dryRun = true;
+    if (typeof ctx.flags.namespace === 'string' && ctx.flags.namespace.length > 0) {
+        cfg.namespaces = ctx.flags.namespace.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    if (ctx.flags.batchSize !== undefined)
+        cfg.batchSize = Number(ctx.flags.batchSize);
+    if (ctx.flags.dedupDistance !== undefined)
+        cfg.dedupDistance = Number(ctx.flags.dedupDistance);
+    if (ctx.flags.maxEntries !== undefined)
+        cfg.maxEntries = Number(ctx.flags.maxEntries);
+    if (ctx.flags.since !== undefined)
+        cfg.sinceRowid = Number(ctx.flags.since);
+    if (ctx.flags.budgetUsd !== undefined)
+        cfg.budgetUsd = Number(ctx.flags.budgetUsd);
+    if (ctx.flags.judge !== undefined) {
+        if (ctx.flags.judge !== 'structural' && ctx.flags.judge !== 'fable') {
+            return { ok: false, error: `--judge must be 'structural' or 'fable' (got '${String(ctx.flags.judge)}')` };
+        }
+        cfg.judge = ctx.flags.judge;
+    }
+    return { ok: true, config: cfg };
+}
+function resolveDbPath(ctx) {
+    return ctx.flags.db || defaultMemoryDbPath(ctx.cwd || process.cwd());
+}
+// ============================================================================
+// `memory distill run`
+// ============================================================================
+const runCommand = {
+    name: 'run',
+    description: 'Distill memory_entries into episodes/reasoning_patterns/pattern_embeddings/causal_edges (ADR-174)',
+    options: [
+        { name: 'dry-run', description: 'Report counts, write nothing', type: 'boolean', default: false },
+        { name: 'namespace', description: 'Comma-separated namespace scope (default: all embedded namespaces)', type: 'string' },
+        { name: 'batch-size', description: 'Rows per transaction (default 200)', type: 'number', default: 200 },
+        { name: 'dedup-distance', description: 'Cosine distance for pattern clustering (default 0.12)', type: 'number', default: 0.12 },
+        { name: 'max-entries', description: 'Per-invocation work cap (default unbounded)', type: 'number' },
+        { name: 'since', description: 'Override the incremental cursor and rescan from this rowid', type: 'number' },
+        { name: 'budget-usd', description: '$0 by default; >0 required to unlock --judge fable (ADR-172)', type: 'number', default: 0 },
+        { name: 'judge', description: "'structural' (default, $0) or 'fable' (requires --budget-usd > 0)", type: 'string', default: 'structural', choices: ['structural', 'fable'] },
+        { name: 'aggressive', description: 'Preset: dedup-distance 0.2, batch-size 500', type: 'boolean' },
+        { name: 'conservative', description: 'Preset: dedup-distance 0.08, batch-size 100', type: 'boolean' },
+        { name: 'config', description: 'Load options from a JSON config file (see: memory distill config)', type: 'string' },
+        { ...DB_OPTION },
+        { name: 'verbose', short: 'v', description: 'Verbose service logging', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'claude-flow memory distill run --dry-run', description: 'Preview counts without writing anything' },
+        { command: 'claude-flow memory distill run --namespace feedback,commands', description: 'Scope the run to specific namespaces' },
+        { command: 'claude-flow memory distill run --aggressive', description: 'Larger batches, looser dedup clustering' },
+        { command: 'claude-flow memory distill run --judge fable --budget-usd 2', description: 'Opt into the cost-bounded Fable judge (ADR-172)' },
+    ],
+    action: async (ctx) => {
+        const resolved = resolveDistillConfig(ctx);
+        if (!resolved.ok) {
+            output.printError(resolved.error);
+            return { success: false, exitCode: 1 };
+        }
+        const config = resolved.config;
+        // Fail-fast ADR-172 gate: the Fable judge is cost-bounded and opt-in only.
+        if (config.judge === 'fable' && !(config.budgetUsd > 0)) {
+            output.printError('--judge fable requires --budget-usd > 0 (ADR-172 cost-bounded advisor path). ' +
+                'Refusing to run the LLM judge against a $0 budget.');
+            return { success: false, exitCode: 1 };
+        }
+        const dbPath = resolveDbPath(ctx);
+        output.writeln();
+        output.writeln(output.bold('Memory Distillation (ADR-174)'));
+        output.writeln(output.dim('─'.repeat(55)));
+        if (config.dryRun)
+            output.writeln(output.warning('DRY RUN — no writes will be made'));
+        const spinner = output.createSpinner({ text: 'Distilling memory_entries...', spinner: 'dots' });
+        spinner.start();
+        const distillOptions = {
+            dbPath,
+            namespaces: config.namespaces,
+            batchSize: config.batchSize,
+            maxEntries: config.maxEntries,
+            dedupDistance: config.dedupDistance,
+            dryRun: config.dryRun,
+            judge: config.judge,
+            sinceRowid: config.sinceRowid,
+            verbose: ctx.flags.verbose === true,
+        };
+        let report;
+        try {
+            report = await runDistillation(distillOptions);
+        }
+        catch (error) {
+            spinner.fail('Distillation failed');
+            output.printError(error instanceof Error ? error.message : String(error));
+            return { success: false, exitCode: 1 };
+        }
+        if (report.skipped) {
+            spinner.succeed('Distillation skipped');
+            output.writeln(output.warning(`skipped: ${report.skipped}`));
+            return { success: true, data: { dbPath, config, report } };
+        }
+        spinner.succeed(config.dryRun ? 'Dry-run complete' : 'Distillation complete');
+        output.writeln();
+        output.printTable({
+            columns: [
+                { key: 'metric', header: 'Metric', width: 24 },
+                { key: 'value', header: 'Value', width: 20 },
+            ],
+            data: [
+                { metric: 'Processed', value: String(report.processed) },
+                { metric: 'Episodes', value: String(report.episodes) },
+                { metric: 'Patterns', value: String(report.patterns) },
+                { metric: 'Pattern Embeddings', value: String(report.patternEmbeddings) },
+                { metric: 'Causal Edges', value: String(report.causalEdges) },
+                { metric: 'Promoted (ADR-171)', value: String(report.promoted) },
+                { metric: 'Namespaces', value: report.namespaces.join(', ') || '(none)' },
+                { metric: 'Spend', value: `$${report.spendUsd.toFixed(4)}` },
+                { metric: 'Dry Run', value: report.dryRun ? 'yes' : 'no' },
+            ],
+        });
+        const provenanceEntries = Object.entries(report.byProvenance);
+        if (provenanceEntries.length > 0) {
+            output.writeln();
+            output.writeln(output.bold('By Provenance'));
+            output.printList(provenanceEntries.map(([tier, count]) => `${output.highlight(tier)}: ${count}`));
+        }
+        return { success: true, data: { dbPath, config, report } };
+    },
+};
+// ============================================================================
+// `memory distill status`
+// ============================================================================
+const statusCommand = {
+    name: 'status',
+    description: 'Read-only report: target table row counts, per-namespace distill_state cursor, promoted vs proxy breakdown',
+    options: [{ ...DB_OPTION }],
+    examples: [
+        { command: 'claude-flow memory distill status', description: 'Show distillation state for the default DB' },
+        { command: 'claude-flow memory distill status --db ./copy.db', description: 'Inspect a specific DB copy' },
+    ],
+    action: async (ctx) => {
+        const dbPath = resolveDbPath(ctx);
+        output.writeln();
+        output.writeln(output.bold('Memory Distillation Status'));
+        output.writeln(output.dim('─'.repeat(55)));
+        if (!fs.existsSync(dbPath)) {
+            output.writeln(output.warning(`No memory DB found at ${dbPath}`));
+            return { success: true, data: { available: false, dbPath, reason: 'no-db' } };
+        }
+        // Optional native dep — hidden behind a variable specifier so the
+        // compiler never statically requires `better-sqlite3` types (same
+        // pattern as ../memory/graph-edge-writer.ts).
+        let Database;
+        try {
+            const mod = 'better-sqlite3';
+            Database = (await import(mod)).default;
+        }
+        catch {
+            output.writeln(output.warning('better-sqlite3 native module unavailable — cannot read distillation state.'));
+            return { success: true, data: { available: false, dbPath, reason: 'better-sqlite3 unavailable' } };
+        }
+        let db;
+        try {
+            db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        }
+        catch (error) {
+            output.printError(`Failed to open ${dbPath}: ${error instanceof Error ? error.message : String(error)}`);
+            return { success: true, data: { available: false, dbPath, reason: 'open-failed' } };
+        }
+        try {
+            const tableExists = (name) => (db.prepare("SELECT COUNT(*) AS c FROM sqlite_master WHERE type='table' AND name=?").get(name)?.c ?? 0) > 0;
+            const targetTables = ['episodes', 'reasoning_patterns', 'pattern_embeddings', 'causal_edges'];
+            const presence = {};
+            for (const t of [...targetTables, 'distill_state'])
+                presence[t] = tableExists(t);
+            const counts = {};
+            for (const t of targetTables) {
+                counts[t] = presence[t] ? (db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get()?.c ?? 0) : 0;
+            }
+            let cursors = [];
+            if (presence.distill_state) {
+                cursors = db.prepare('SELECT namespace AS namespace, last_rowid AS lastRowid, last_run_at AS lastRunAt FROM distill_state ORDER BY namespace').all();
+            }
+            let promoted = 0;
+            let proxy = 0;
+            if (presence.reasoning_patterns) {
+                promoted = db.prepare("SELECT COUNT(*) AS c FROM reasoning_patterns WHERE json_extract(metadata,'$.promoted')=1").get()?.c ?? 0;
+                proxy = db.prepare("SELECT COUNT(*) AS c FROM reasoning_patterns WHERE json_extract(metadata,'$.provenance')='proxy:structural'").get()?.c ?? 0;
+            }
+            db.close();
+            output.printTable({
+                columns: [
+                    { key: 'table', header: 'Table', width: 22 },
+                    { key: 'rows', header: 'Rows', width: 10 },
+                ],
+                data: targetTables.map((t) => ({ table: t, rows: String(counts[t]) })),
+            });
+            output.writeln();
+            output.writeln(output.bold('Promote gate (ADR-171)'));
+            output.writeln(`  promoted: ${promoted}   proxy (never promoted): ${proxy}   total patterns: ${counts.reasoning_patterns}`);
+            if (cursors.length > 0) {
+                output.writeln();
+                output.writeln(output.bold('distill_state cursor'));
+                output.printTable({
+                    columns: [
+                        { key: 'namespace', header: 'Namespace', width: 20 },
+                        { key: 'lastRowid', header: 'Last Rowid', width: 12 },
+                        { key: 'lastRunAt', header: 'Last Run', width: 26 },
+                    ],
+                    data: cursors.map((c) => ({
+                        namespace: c.namespace,
+                        lastRowid: String(c.lastRowid),
+                        lastRunAt: c.lastRunAt ? new Date(c.lastRunAt).toISOString() : 'never',
+                    })),
+                });
+            }
+            else {
+                output.writeln();
+                output.writeln(output.dim('No distill_state cursor rows yet (run `memory distill run` first).'));
+            }
+            if (!presence.reasoning_patterns) {
+                output.writeln();
+                output.writeln(output.dim('Target tables not present — agentdb schema not initialised, or distillation never run.'));
+            }
+            return {
+                success: true,
+                data: { available: true, dbPath, counts, cursors, promoted, proxy, tablesPresent: presence },
+            };
+        }
+        catch (error) {
+            try {
+                db?.close();
+            }
+            catch { /* best-effort */ }
+            output.printError(error instanceof Error ? error.message : String(error));
+            return { success: true, data: { available: false, dbPath, reason: 'error' } };
+        }
+    },
+};
+// ============================================================================
+// `memory distill config`
+// ============================================================================
+const configCommand = {
+    name: 'config',
+    description: 'Print the effective distill config (defaults + --config file + preset + explicit flags) as JSON',
+    options: [
+        { name: 'config', description: 'Load options from a JSON config file', type: 'string' },
+        { name: 'aggressive', description: 'Preset: dedup-distance 0.2, batch-size 500', type: 'boolean' },
+        { name: 'conservative', description: 'Preset: dedup-distance 0.08, batch-size 100', type: 'boolean' },
+        { name: 'namespace', description: 'Comma-separated namespace scope', type: 'string' },
+        { name: 'batch-size', description: 'Rows per transaction', type: 'number' },
+        { name: 'dedup-distance', description: 'Cosine distance for pattern clustering', type: 'number' },
+        { name: 'max-entries', description: 'Per-invocation work cap', type: 'number' },
+        { name: 'since', description: 'Override incremental cursor start (rowid)', type: 'number' },
+        { name: 'budget-usd', description: '$0 by default', type: 'number' },
+        { name: 'judge', description: "'structural' | 'fable'", type: 'string' },
+        { ...DB_OPTION },
+    ],
+    examples: [
+        { command: 'claude-flow memory distill config', description: 'Print the platform-default config' },
+        { command: 'claude-flow memory distill config --aggressive', description: 'Print the effective config with the aggressive preset applied' },
+    ],
+    action: async (ctx) => {
+        const resolved = resolveDistillConfig(ctx);
+        if (!resolved.ok) {
+            output.printError(resolved.error);
+            return { success: false, exitCode: 1 };
+        }
+        const dbPath = resolveDbPath(ctx);
+        const payload = { dbPath, ...resolved.config };
+        output.writeln(JSON.stringify(payload, null, 2));
+        return { success: true, data: payload };
+    },
+};
+// ============================================================================
+// `memory distill` (parent)
+// ============================================================================
+export const distillCommand = {
+    name: 'distill',
+    description: 'Memory distillation (ADR-174): mine memory_entries into reasoning_patterns/episodes/causal_edges',
+    subcommands: [runCommand, statusCommand, configCommand],
+    examples: [
+        { command: 'claude-flow memory distill run --dry-run', description: 'Preview a distillation pass' },
+        { command: 'claude-flow memory distill status', description: 'Show distilled table counts + cursor' },
+        { command: 'claude-flow memory distill config --conservative', description: 'Print the effective conservative-preset config' },
+    ],
+    action: async () => {
+        output.writeln();
+        output.writeln(output.bold('Memory Distillation (ADR-174)'));
+        output.writeln('Usage: claude-flow memory distill <run|status|config> [options]');
+        output.writeln();
+        output.printList([
+            `${output.highlight('run')}     - Distill memory_entries into the structured intelligence tables`,
+            `${output.highlight('status')}  - Report target table counts, cursor, and promote-gate breakdown`,
+            `${output.highlight('config')}  - Print the effective resolved config as JSON`,
+        ]);
+        return { success: true };
+    },
+};
+export default distillCommand;
+//# sourceMappingURL=memory-distill.js.map

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

@@ -5,6 +5,7 @@
 import { output } from '../output.js';
 import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
+import { distillCommand } from './memory-distill.js';
 // Memory backends
 const BACKENDS = [
     { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
@@ -1471,7 +1472,7 @@ const initMemoryCommand = {
 export const memoryCommand = {
     name: 'memory',
     description: 'Memory management commands',
-    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand],
+    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
@@ -1497,7 +1498,8 @@ export const memoryCommand = {
             `${output.highlight('cleanup')}    - Clean expired entries`,
             `${output.highlight('compress')}   - Compress database`,
             `${output.highlight('export')}     - Export memory to file`,
-            `${output.highlight('import')}     - Import from file`
+            `${output.highlight('import')}     - Import from file`,
+            `${output.highlight('distill')}    - Distill memory_entries into structured intelligence (ADR-174)`
         ]);
         return { success: true };
     }

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

@@ -63,7 +63,7 @@ export { OutputFormatter, output, Progress, Spinner, type VerbosityLevel } from
 export * from './prompt.js';
 export * from './commands/index.js';
 export { MCPServerManager, createMCPServerManager, getServerManager, startMCPServer, stopMCPServer, getMCPServerStatus, type MCPServerOptions, type MCPServerStatus, } from './mcp-server.js';
-export { initializeMemoryDatabase, generateEmbedding, generateBatchEmbeddings, storeEntry, searchEntries, getHNSWIndex, addToHNSWIndex, searchHNSWIndex, getHNSWStatus, clearHNSWIndex, quantizeInt8, dequantizeInt8, quantizedCosineSim, getQuantizationStats, batchCosineSim, softmaxAttention, topKIndices, flashAttentionSearch, type MemoryInitResult, } from './memory/memory-initializer.js';
+export { initializeMemoryDatabase, repairVectorIndexes, recoverMemoryDatabase, generateEmbedding, generateBatchEmbeddings, storeEntry, searchEntries, getHNSWIndex, addToHNSWIndex, searchHNSWIndex, getHNSWStatus, clearHNSWIndex, quantizeInt8, dequantizeInt8, quantizedCosineSim, getQuantizationStats, batchCosineSim, softmaxAttention, topKIndices, flashAttentionSearch, type MemoryInitResult, } from './memory/memory-initializer.js';
 export { initializeIntelligence, recordStep, recordTrajectory, findSimilarPatterns, getIntelligenceStats, getSonaCoordinator, getReasoningBank, clearIntelligence, benchmarkAdaptation, endTrajectoryWithVerdict, distillLearning, getAllPatterns, getPatternsByType, flushPatterns, deletePattern, clearAllPatterns, getNeuralDataDir, getPersistenceStatus, type SonaConfig, type TrajectoryStep, type Pattern, type IntelligenceStats, } from './memory/intelligence.js';
 export { EWCConsolidator, getEWCConsolidator, resetEWCConsolidator, consolidatePatterns, recordPatternOutcome, getEWCStats, type PatternWeights, type EWCConfig, type ConsolidationResult, type EWCStats, } from './memory/ewc-consolidation.js';
 export { SONAOptimizer, getSONAOptimizer, resetSONAOptimizer, processTrajectory, getSuggestion, getSONAStats, type TrajectoryOutcome, type LearnedPattern, type RoutingSuggestion, type SONAStats, } from './memory/sona-optimizer.js';

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

@@ -113,6 +113,27 @@ export class CLI {
             if (!flags.noUpdate && commandPath[0] !== 'update') {
                 this.checkForUpdatesOnStartup().catch(() => { });
             }
+            // Version-stamped helper auto-refresh — propagate hook fixes to an already
+            // initialized project without a manual re-init. Skip for init/upgrade
+            // (they refresh explicitly). AWAITED (not fire-and-forget) so a fast
+            // command can't exit before the copy lands; the fast path is a single
+            // stamp read + string compare (sub-ms), and the copy runs at most once per
+            // version bump. Best-effort + silent — never blocks or fails a command.
+            if (commandPath[0] !== 'init' && commandPath[0] !== 'update') {
+                try {
+                    const { autoRefreshHelpersIfStale } = await import('./init/helper-refresh.js');
+                    const r = await autoRefreshHelpersIfStale(process.cwd());
+                    if (r.blocked) {
+                        // Integrity failure = potential on-disk tampering of hook code. Warn
+                        // loudly (not silent) — the existing project helpers were left intact.
+                        this.output.printWarning(`Skipped helper auto-refresh — ${r.blocked}. Reinstall @claude-flow/cli from a trusted source.`);
+                    }
+                    else if (r.refreshed && this.output.isVerbose()) {
+                        this.output.printDebug(`Refreshed .claude/helpers (${r.from} → ${r.to})`);
+                    }
+                }
+                catch { /* silent */ }
+            }
             // Handle lazy-loaded commands that weren't recognized by the parser
             // If commandPath is empty but positional has a command name, check if it's lazy-loadable
             if (commandPath.length === 0 && positional.length > 0 && !positional[0].startsWith('-')) {
@@ -515,7 +536,7 @@ export * from './commands/index.js';
 // MCP Server management
 export { MCPServerManager, createMCPServerManager, getServerManager, startMCPServer, stopMCPServer, getMCPServerStatus, } from './mcp-server.js';
 // Memory & Intelligence (V3 Performance Features)
-export { initializeMemoryDatabase, generateEmbedding, generateBatchEmbeddings, storeEntry, searchEntries, getHNSWIndex, addToHNSWIndex, searchHNSWIndex, getHNSWStatus, clearHNSWIndex, quantizeInt8, dequantizeInt8, quantizedCosineSim, getQuantizationStats, 
+export { initializeMemoryDatabase, repairVectorIndexes, recoverMemoryDatabase, generateEmbedding, generateBatchEmbeddings, storeEntry, searchEntries, getHNSWIndex, addToHNSWIndex, searchHNSWIndex, getHNSWStatus, clearHNSWIndex, quantizeInt8, dequantizeInt8, quantizedCosineSim, getQuantizationStats, 
 // Flash Attention-style batch operations
 batchCosineSim, softmaxAttention, topKIndices, flashAttentionSearch, } from './memory/memory-initializer.js';
 export { initializeIntelligence, recordStep, recordTrajectory, findSimilarPatterns, getIntelligenceStats, getSonaCoordinator, getReasoningBank, clearIntelligence, benchmarkAdaptation,