claude-flow 3.22.0 → 3.23.0

package/package.json

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

@@ -6,6 +6,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';
+import { backupCommand } from './memory-backup.js';
 // Memory backends
 const BACKENDS = [
     { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
@@ -1472,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, distillCommand],
+    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' },

package/v3/@claude-flow/cli/dist/src/services/memory-backup.d.ts

@@ -0,0 +1,24 @@
+export interface BackupOptions {
+    /** Source DB (default: <cwd>/.swarm/memory.db). */
+    dbPath?: string;
+    /** Destination dir (default: <db dir>/backups). */
+    destDir?: string;
+    /** Rotation: keep the newest N snapshots (default 7 = a week of nightlies). */
+    keep?: number;
+    /** Optional offsite: a gs://bucket/prefix to also upload the snapshot to. */
+    gcs?: string;
+    /** Injected epoch millis (tests pass a fixed value; avoids Date.now in logic). */
+    timestamp?: number;
+    verbose?: boolean;
+}
+export interface BackupResult {
+    backedUp: boolean;
+    path?: string;
+    sizeBytes?: number;
+    rotatedAway?: string[];
+    gcsUri?: string;
+    skipped?: string;
+}
+export declare function defaultMemoryDbPath(cwd?: string): string;
+export declare function backupMemoryDb(opts?: BackupOptions): Promise<BackupResult>;
+//# sourceMappingURL=memory-backup.d.ts.map

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

@@ -0,0 +1,94 @@
+/**
+ * Vector-memory DB backup.
+ *
+ * Snapshots `.swarm/memory.db` (the sqlite store holding memory_entries +
+ * embeddings + the distilled reasoning_patterns) to a timestamped file using
+ * better-sqlite3's ONLINE backup API — a consistent, WAL-safe copy that does not
+ * block or corrupt a concurrently-written DB (unlike a naive file copy of a
+ * WAL-mode DB). Rotates to keep the last N snapshots and, optionally, uploads
+ * offsite to Google Cloud Storage.
+ *
+ * Used by `memory backup` (manual) and the daemon's nightly `backup` worker.
+ * Best-effort + non-destructive: it only reads the source DB and writes new
+ * files; it never mutates or deletes the live memory DB.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export function defaultMemoryDbPath(cwd = process.cwd()) {
+    return path.join(cwd, '.swarm', 'memory.db');
+}
+/** ISO timestamp safe for filenames (no ':' or '.'). */
+function fileStamp(ms) {
+    return new Date(ms).toISOString().replace(/[:.]/g, '-');
+}
+export async function backupMemoryDb(opts = {}) {
+    const dbPath = opts.dbPath ?? defaultMemoryDbPath();
+    if (!dbPath || !fs.existsSync(dbPath))
+        return { backedUp: false, skipped: 'no-db' };
+    let Database;
+    try {
+        const mod = 'better-sqlite3';
+        Database = (await import(mod)).default;
+    }
+    catch {
+        return { backedUp: false, skipped: 'better-sqlite3 unavailable' };
+    }
+    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
+    try {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+    catch { /* */ }
+    const destPath = path.join(destDir, `memory-${fileStamp(opts.timestamp ?? Date.now())}.db`);
+    // WAL-safe online backup: read-only source, consistent snapshot to destPath.
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true });
+        await db.backup(destPath);
+        db.close();
+    }
+    catch (e) {
+        try {
+            db?.close();
+        }
+        catch { /* */ }
+        return { backedUp: false, skipped: `backup failed: ${e?.message ?? e}` };
+    }
+    let sizeBytes = 0;
+    try {
+        sizeBytes = fs.statSync(destPath).size;
+    }
+    catch { /* */ }
+    // Rotation — ISO-stamped names sort chronologically, so keep the tail.
+    const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
+    const rotatedAway = [];
+    try {
+        const snaps = fs.readdirSync(destDir).filter(f => /^memory-.*\.db$/.test(f)).sort();
+        while (snaps.length > keep) {
+            const old = snaps.shift();
+            try {
+                fs.rmSync(path.join(destDir, old), { force: true });
+                rotatedAway.push(old);
+            }
+            catch { /* */ }
+        }
+    }
+    catch { /* */ }
+    // Optional offsite to GCS (best-effort; local backup already succeeded).
+    let gcsUri;
+    if (opts.gcs) {
+        try {
+            const { execFileSync } = await import('child_process');
+            const dest = opts.gcs.replace(/\/+$/, '') + '/' + path.basename(destPath);
+            execFileSync('gcloud', ['storage', 'cp', destPath, dest], { stdio: ['ignore', 'ignore', 'inherit'] });
+            gcsUri = dest;
+        }
+        catch { /* offsite failed — local snapshot stands */ }
+    }
+    if (opts.verbose) {
+        console.log(`memory DB backed up → ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
+            (rotatedAway.length ? `, rotated ${rotatedAway.length} old` : '') +
+            (gcsUri ? `, offsite ${gcsUri}` : ''));
+    }
+    return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri };
+}
+//# sourceMappingURL=memory-backup.js.map

package/v3/@claude-flow/cli/dist/src/services/worker-daemon.d.ts

@@ -12,7 +12,7 @@
  */
 import { EventEmitter } from 'events';
 import { HeadlessWorkerExecutor } from './headless-worker-executor.js';
-export type WorkerType = 'ultralearn' | 'optimize' | 'consolidate' | 'predict' | 'audit' | 'map' | 'preload' | 'deepdive' | 'document' | 'refactor' | 'benchmark' | 'testgaps';
+export type WorkerType = 'ultralearn' | 'optimize' | 'consolidate' | 'predict' | 'audit' | 'map' | 'preload' | 'deepdive' | 'document' | 'refactor' | 'benchmark' | 'testgaps' | 'backup';
 interface WorkerConfig {
     type: WorkerType;
     intervalMs: number;
@@ -319,6 +319,14 @@ export declare class WorkerDaemon extends EventEmitter {
      *    call defensively — a background worker must never crash the daemon.
      */
     private runConsolidateWorker;
+    /**
+     * Nightly memory-DB backup worker (24h interval). Takes a WAL-safe, consistent
+     * snapshot of .swarm/memory.db with rotation (keep last N). Never throws — a
+     * worker must not crash the daemon; a skip/error is written to the metrics
+     * file. Opt-out by omitting `backup` from `-w`; offsite GCS is opt-in via
+     * RUFLO_BACKUP_GCS (a gs:// prefix), retention via RUFLO_BACKUP_KEEP.
+     */
+    private runBackupWorker;
     /**
      * Local testgaps worker (fallback when headless unavailable)
      */

package/v3/@claude-flow/cli/dist/src/services/worker-daemon.js

@@ -21,6 +21,7 @@ import { HeadlessWorkerExecutor, isHeadlessWorker, } from './headless-worker-exe
 // incremental (rowid cursor), non-destructive, transactional, and
 // quick_check-gated, so it's safe to call unconditionally on every tick.
 import { runDistillation, defaultMemoryDbPath } from './memory-distillation.js';
+import { backupMemoryDb } from './memory-backup.js';
 // Default worker configurations with improved intervals (P0 fix: map 5min -> 15min)
 const DEFAULT_WORKERS = [
     { type: 'map', intervalMs: 15 * 60 * 1000, offsetMs: 0, priority: 'normal', description: 'Codebase mapping', enabled: true },
@@ -28,6 +29,7 @@ const DEFAULT_WORKERS = [
     { type: 'optimize', intervalMs: 15 * 60 * 1000, offsetMs: 4 * 60 * 1000, priority: 'high', description: 'Performance optimization', enabled: true },
     { type: 'consolidate', intervalMs: 30 * 60 * 1000, offsetMs: 6 * 60 * 1000, priority: 'low', description: 'Memory distillation (ADR-174)', enabled: true },
     { type: 'testgaps', intervalMs: 20 * 60 * 1000, offsetMs: 8 * 60 * 1000, priority: 'normal', description: 'Test coverage analysis', enabled: true },
+    { type: 'backup', intervalMs: 24 * 60 * 60 * 1000, offsetMs: 10 * 60 * 1000, priority: 'low', description: 'Nightly memory DB backup (WAL-safe, rotated)', enabled: true },
     { type: 'predict', intervalMs: 10 * 60 * 1000, offsetMs: 0, priority: 'low', description: 'Predictive preloading', enabled: false },
     { type: 'document', intervalMs: 60 * 60 * 1000, offsetMs: 0, priority: 'low', description: 'Auto-documentation', enabled: false },
 ];
@@ -1158,6 +1160,8 @@ export class WorkerDaemon extends EventEmitter {
                 return this.runOptimizeWorkerLocal();
             case 'consolidate':
                 return this.runConsolidateWorker();
+            case 'backup':
+                return this.runBackupWorker();
             case 'testgaps':
                 return this.runTestGapsWorkerLocal();
             case 'predict':
@@ -1395,6 +1399,44 @@ export class WorkerDaemon extends EventEmitter {
         writeFileSync(consolidateFile, JSON.stringify(result, null, 2));
         return result;
     }
+    /**
+     * Nightly memory-DB backup worker (24h interval). Takes a WAL-safe, consistent
+     * snapshot of .swarm/memory.db with rotation (keep last N). Never throws — a
+     * worker must not crash the daemon; a skip/error is written to the metrics
+     * file. Opt-out by omitting `backup` from `-w`; offsite GCS is opt-in via
+     * RUFLO_BACKUP_GCS (a gs:// prefix), retention via RUFLO_BACKUP_KEEP.
+     */
+    async runBackupWorker() {
+        const metricsDir = join(this.projectRoot, '.claude-flow', 'metrics');
+        if (!existsSync(metricsDir))
+            mkdirSync(metricsDir, { recursive: true });
+        const backupFile = join(metricsDir, 'backup.json');
+        let result;
+        try {
+            const keepEnv = Number(process.env.RUFLO_BACKUP_KEEP);
+            const r = await backupMemoryDb({
+                dbPath: defaultMemoryDbPath(this.projectRoot),
+                keep: Number.isFinite(keepEnv) && keepEnv > 0 ? keepEnv : 7,
+                gcs: process.env.RUFLO_BACKUP_GCS || undefined,
+            });
+            result = {
+                timestamp: new Date().toISOString(),
+                backedUp: r.backedUp,
+                path: r.path,
+                sizeBytes: r.sizeBytes ?? 0,
+                rotatedAway: r.rotatedAway?.length ?? 0,
+                gcsUri: r.gcsUri,
+                skipped: r.skipped,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log('warn', `Backup worker failed: ${message}`);
+            result = { timestamp: new Date().toISOString(), backedUp: false, error: message };
+        }
+        writeFileSync(backupFile, JSON.stringify(result, null, 2));
+        return result;
+    }
     /**
      * Local testgaps worker (fallback when headless unavailable)
      */

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

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