@claude-flow/cli 3.21.0 → 3.22.0

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

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