π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(memory): nightly vector-DB backup β WAL-safe snapshot, rotation, daemon worker (#2571)
rUv802b75b4e2f1
diff --git a/scripts/audit-env-var-precedence.mjs b/scripts/audit-env-var-precedence.mjsindex 4881c8f341..ee5eb80d79 100644--- a/scripts/audit-env-var-precedence.mjs+++ b/scripts/audit-env-var-precedence.mjs@@ -181,6 +181,11 @@ const KNOWN_ESCAPE_HATCHES = new Set(['CLAUDE_FLOW_RUN_TRANSCRIPTS_MAXROTATIONS','CLAUDE_FLOW_RUN_TRANSCRIPTS_MAXSIZE','CLAUDE_FLOW_SWARM_DIR', // Set by ruflo init / inter-process β not user-typed+ // Nightly backup daemon-worker config (ADR-174 follow-up). The interactive+ // `memory backup` command exposes --keep / --gcs / --dir flags with proper+ // precedence; these env vars only configure the headless daemon worker path.+ 'RUFLO_BACKUP_KEEP',+ 'RUFLO_BACKUP_GCS',]);// ββ Source directories to scan ββββββββββββββββββββββββββββββββββββββββββββββββdiff --git a/v3/@claude-flow/cli/__tests__/memory-backup.test.ts b/v3/@claude-flow/cli/__tests__/memory-backup.test.tsnew file mode 100644index 0000000000..f9ca099747--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/memory-backup.test.ts@@ -0,0 +1,76 @@+/**+ * Vector-memory DB backup service (nightly backup worker + `memory backup`).+ *+ * Proves the WAL-safe snapshot is consistent, non-destructive, rotated, and+ * degrades cleanly when there's nothing to back up.+ */+import { describe, it, expect, beforeEach } from 'vitest';+import { mkdtempSync, existsSync, readdirSync, statSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';++import { backupMemoryDb } from '../src/services/memory-backup.js';++let Database: any;+let haveNative = false;+try { Database = (await import('better-sqlite3')).default; haveNative = true; } catch { haveNative = false; }++function seedDb(dbPath: string, rows = 50): void {+ const db = new Database(dbPath);+ db.pragma('journal_mode = WAL'); // the mode a naive copy would corrupt+ db.exec('CREATE TABLE memory_entries (id INTEGER PRIMARY KEY, content TEXT)');+ const ins = db.prepare('INSERT INTO memory_entries (content) VALUES (?)');+ const tx = db.transaction(() => { for (let i = 0; i < rows; i++) ins.run('row ' + i); });+ tx();+ db.close();+}++describe.skipIf(!haveNative)('backupMemoryDb', () => {+ let workdir: string;+ beforeEach(() => { workdir = mkdtempSync(join(tmpdir(), 'mem-backup-')); });++ it('takes a consistent WAL-safe snapshot without mutating the source', async () => {+ const dbPath = join(workdir, 'memory.db');+ seedDb(dbPath, 50);+ const srcSize = statSync(dbPath).size;++ const r = await backupMemoryDb({ dbPath, timestamp: 1_700_000_000_000 });+ expect(r.backedUp).toBe(true);+ expect(existsSync(r.path!)).toBe(true);+ expect(r.sizeBytes!).toBeGreaterThan(0);++ // Source is unchanged (size stable) and the snapshot has all the rows.+ expect(statSync(dbPath).size).toBe(srcSize);+ const snap = new Database(r.path!, { readonly: true });+ const count = (snap.prepare('SELECT COUNT(*) AS c FROM memory_entries').get() as { c: number }).c;+ snap.close();+ expect(count).toBe(50);+ });++ it('defaults the destination to <db dir>/backups', async () => {+ const dbPath = join(workdir, 'memory.db');+ seedDb(dbPath);+ const r = await backupMemoryDb({ dbPath, timestamp: 1_700_000_000_000 });+ expect(r.path!.replace(/\\/g, '/')).toContain('/backups/memory-');+ });++ it('rotates β keeps only the newest N snapshots', async () => {+ const dbPath = join(workdir, 'memory.db');+ seedDb(dbPath);+ const destDir = join(workdir, 'backups');+ // 5 snapshots at increasing timestamps, keep=3.+ for (let i = 0; i < 5; i++) {+ await backupMemoryDb({ dbPath, destDir, keep: 3, timestamp: 1_700_000_000_000 + i * 86_400_000 });+ }+ const snaps = readdirSync(destDir).filter(f => /^memory-.*\.db$/.test(f));+ expect(snaps.length).toBe(3);+ // The three newest (largest timestamps) survive.+ expect(snaps.sort().slice(-1)[0]).toContain('memory-');+ });++ it('is a safe no-op when there is no DB to back up', async () => {+ const r = await backupMemoryDb({ dbPath: join(workdir, 'nope.db') });+ expect(r.backedUp).toBe(false);+ expect(r.skipped).toBe('no-db');+ });+});diff --git a/v3/@claude-flow/cli/src/commands/memory-backup.ts b/v3/@claude-flow/cli/src/commands/memory-backup.tsnew file mode 100644index 0000000000..c03e105366--- /dev/null+++ b/v3/@claude-flow/cli/src/commands/memory-backup.ts@@ -0,0 +1,57 @@+/**+ * 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, CommandContext, CommandResult } from '../types.js';+import { output } from '../output.js';+import { backupMemoryDb, defaultMemoryDbPath } from '../services/memory-backup.js';++export const backupCommand: Command = {+ 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: CommandContext): Promise<CommandResult> => {+ const r = await backupMemoryDb({+ dbPath: (ctx.flags.db as string) || defaultMemoryDbPath(ctx.cwd),+ destDir: ctx.flags.dir as string | undefined,+ keep: typeof ctx.flags.keep === 'number' ? (ctx.flags.keep as number) : 7,+ gcs: ctx.flags.gcs as string | undefined,+ 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;diff --git a/v3/@claude-flow/cli/src/commands/memory.ts b/v3/@claude-flow/cli/src/commands/memory.tsindex dbc48ae075..a4051d1fb7 100644--- a/v3/@claude-flow/cli/src/commands/memory.ts+++ b/v3/@claude-flow/cli/src/commands/memory.ts@@ -8,6 +8,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 backendsconst BACKENDS = [@@ -1684,7 +1685,7 @@ const initMemoryCommand: Command = {export const memoryCommand: Command = {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' },diff --git a/v3/@claude-flow/cli/src/services/memory-backup.ts b/v3/@claude-flow/cli/src/services/memory-backup.tsnew file mode 100644index 0000000000..a6e754f773--- /dev/null+++ b/v3/@claude-flow/cli/src/services/memory-backup.ts@@ -0,0 +1,110 @@+/**+ * 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 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 function defaultMemoryDbPath(cwd: string = process.cwd()): string {+ return path.join(cwd, '.swarm', 'memory.db');+}++/** ISO timestamp safe for filenames (no ':' or '.'). */+function fileStamp(ms: number): string {+ return new Date(ms).toISOString().replace(/[:.]/g, '-');+}++export async function backupMemoryDb(opts: BackupOptions = {}): Promise<BackupResult> {+ const dbPath = opts.dbPath ?? defaultMemoryDbPath();+ if (!dbPath || !fs.existsSync(dbPath)) return { backedUp: false, skipped: 'no-db' };++ let Database: any;+ try {+ const mod: string = '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: any;+ 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 as Error)?.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: string[] = [];+ 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: string | undefined;+ 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 };+}diff --git a/v3/@claude-flow/cli/src/services/worker-daemon.ts b/v3/@claude-flow/cli/src/services/worker-daemon.tsindex bb4915810a..5812f4634b 100644--- a/v3/@claude-flow/cli/src/services/worker-daemon.ts+++ b/v3/@claude-flow/cli/src/services/worker-daemon.ts@@ -29,6 +29,7 @@ import {// incremental (rowid cursor), non-destructive, transactional, and// quick_check-gated, so it's safe to call unconditionally on every tick.import { runDistillation, defaultMemoryDbPath, type DistillReport } from './memory-distillation.js';+import { backupMemoryDb } from './memory-backup.js';// Worker types matching hooks-tools.tsexport type WorkerType =@@ -43,7 +44,8 @@ export type WorkerType =| 'document'| 'refactor'| 'benchmark'- | 'testgaps';+ | 'testgaps'+ | 'backup';interface WorkerConfig {type: WorkerType;@@ -119,6 +121,7 @@ const DEFAULT_WORKERS: WorkerConfigInternal[] = [{ 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 },];@@ -1312,6 +1315,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':@@ -1574,6 +1579,45 @@ export class WorkerDaemon extends EventEmitter {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.+ */+ private async runBackupWorker(): Promise<unknown> {+ const metricsDir = join(this.projectRoot, '.claude-flow', 'metrics');+ if (!existsSync(metricsDir)) mkdirSync(metricsDir, { recursive: true });+ const backupFile = join(metricsDir, 'backup.json');++ let result: Record<string, unknown>;+ 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)*/