Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.mjs
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 backends
const 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.ts
new file mode 100644
index 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.ts
index 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.ts
export 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)
*/