claude-flow 3.21.1 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.21.1",
+  "version": "3.23.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/memory-backup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * V3 CLI `memory backup` command.
+ *
+ * WAL-safe snapshot of the vector-memory DB (`.swarm/memory.db`) with rotation
+ * and optional GCS offsite. Thin surface over ../services/memory-backup.js; the
+ * daemon's nightly `backup` worker calls the same service.
+ */
+import type { Command } from '../types.js';
+export declare const backupCommand: Command;
+export default backupCommand;
+//# sourceMappingURL=memory-backup.d.ts.map

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

@@ -0,0 +1,46 @@
+import { output } from '../output.js';
+import { backupMemoryDb, defaultMemoryDbPath } from '../services/memory-backup.js';
+export const backupCommand = {
+    name: 'backup',
+    description: 'Snapshot the vector-memory DB (.swarm/memory.db) — WAL-safe, rotated, optional GCS offsite',
+    options: [
+        { name: 'db', description: 'Source DB (default: .swarm/memory.db)', type: 'string' },
+        { name: 'dir', description: 'Destination dir (default: .swarm/backups)', type: 'string' },
+        { name: 'keep', description: 'Rotation — keep the newest N snapshots (default 7)', type: 'number', default: 7 },
+        { name: 'gcs', description: 'Also upload the snapshot to a gs://bucket/prefix (offsite)', type: 'string' },
+        { name: 'verbose', short: 'v', description: 'Verbose logging', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'claude-flow memory backup', description: 'Snapshot to .swarm/backups, keep last 7' },
+        { command: 'claude-flow memory backup --keep 30', description: 'Keep a month of nightly snapshots' },
+        { command: 'claude-flow memory backup --gcs gs://my-bucket/ruflo-backups', description: 'Also upload offsite to GCS' },
+    ],
+    action: async (ctx) => {
+        const r = await backupMemoryDb({
+            dbPath: ctx.flags.db || defaultMemoryDbPath(ctx.cwd),
+            destDir: ctx.flags.dir,
+            keep: typeof ctx.flags.keep === 'number' ? ctx.flags.keep : 7,
+            gcs: ctx.flags.gcs,
+            verbose: ctx.flags.verbose === true,
+        });
+        if (!r.backedUp) {
+            // no-db is a benign "nothing to back up yet"; anything else is a real skip.
+            if (r.skipped === 'no-db') {
+                output.printWarning('No memory DB found to back up (.swarm/memory.db). Nothing to do.');
+                return { success: true, data: r };
+            }
+            output.printError(`Backup skipped: ${r.skipped}`);
+            return { success: false, exitCode: 1, data: r };
+        }
+        output.writeln();
+        output.writeln(output.success(`Backed up → ${r.path}`));
+        output.printList([
+            `Size:      ${Math.round((r.sizeBytes ?? 0) / 1024)} KB`,
+            `Rotated:   ${r.rotatedAway?.length ?? 0} old snapshot(s) removed`,
+            ...(r.gcsUri ? [`Offsite:   ${r.gcsUri}`] : []),
+        ]);
+        return { success: true, data: r };
+    },
+};
+export default backupCommand;
+//# sourceMappingURL=memory-backup.js.map

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,8 @@
 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';
+import { backupCommand } from './memory-backup.js';
 // Memory backends
 const BACKENDS = [
     { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
@@ -1471,7 +1473,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, backupCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
@@ -1497,7 +1499,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,