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

fix(memory): include active project stores in default backups

Rudy Celekli8337ce103a15
diff --git a/v3/@claude-flow/cli/__tests__/memory-backup-project-stores.test.ts b/v3/@claude-flow/cli/__tests__/memory-backup-project-stores.test.ts
new file mode 100644
index 0000000000..2c11c12a39
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/memory-backup-project-stores.test.ts
@@ -0,0 +1,157 @@
+import { beforeEach, afterEach, it, expect, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import Database from 'better-sqlite3';
+import { backupCommand } from '../src/commands/memory-backup.js';
+import { configCommand } from '../src/commands/config.js';
+import { configManager } from '../src/services/config-file-manager.js';
+import { CommandParser } from '../src/parser.js';
+import { WorkerDaemon } from '../src/services/worker-daemon.js';
+import { getMemoryRoot, _resetMemoryRootCache } from '../src/memory/memory-initializer.js';
+
+let root: string;
+let configured: string;
+function seed(dir: string, name: string, key: string): void {
+ mkdirSync(dir, { recursive: true });
+ const db = new Database(join(dir, name));
+ try {
+ db.exec('CREATE TABLE memory_entries(key TEXT PRIMARY KEY, content TEXT)');
+ db.prepare('INSERT INTO memory_entries VALUES (?, ?)').run(key, 'owned native backup fixture');
+ } finally { db.close(); }
+}
+function keys(dir: string): string[] {
+ return readdirSync(dir).filter(name => name.endsWith('.db')).flatMap(name => {
+ const db = new Database(join(dir, name), { readonly: true });
+ try { return (db.prepare('SELECT key FROM memory_entries').all() as Array<{ key: string }>).map(row => row.key); }
+ finally { db.close(); }
+ }).sort();
+}
+async function backup(...args: string[]) {
+ const parser = new CommandParser();
+ parser.registerCommand(backupCommand);
+ const parsed = parser.parse(['backup', ...args]);
+ expect(parser.validateFlags(parsed.flags, backupCommand)).toEqual([]);
+ return backupCommand.action!({ cwd: root, args: parsed.positional, flags: parsed.flags, interactive: false });
+}
+async function configure(location: string, key: string): Promise<void> {
+ if (location.startsWith('.claude-flow')) mkdirSync(join(root, '.claude-flow'), { recursive: true });
+ writeFileSync(join(root, location), '{}');
+ configManager.load(root);
+ const parser = new CommandParser();
+ parser.registerCommand(configCommand);
+ const set = configCommand.subcommands!.find(command => command.name === 'set')!;
+ const parsed = parser.parse(['config', 'set', key, 'configured-memory']);
+ expect(parser.validateFlags(parsed.flags, set)).toEqual([]);
+ expect((await set.action!({ cwd: root, args: parsed.positional, flags: parsed.flags, interactive: false }))?.success).toBe(true);
+}
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'ruflo-project-backup-'));
+ configured = join(root, 'configured-memory');
+ vi.stubEnv('CLAUDE_FLOW_CONFIG', '');
+ vi.stubEnv('CLAUDE_FLOW_MEMORY_PATH', '');
+ vi.stubEnv('CLAUDE_FLOW_DB_PATH', '');
+ vi.stubEnv('RUFLO_BACKUP_GCS', '');
+ vi.stubEnv('RUFLO_BACKUP_KEEP', '');
+ _resetMemoryRootCache();
+ seed(join(root, '.swarm'), 'memory.db', 'default-cli');
+ seed(join(root, '.swarm'), 'agentdb-memory.db', 'default-mcp');
+ seed(configured, 'memory.db', 'configured-cli');
+ seed(configured, 'agentdb-memory.db', 'configured-mcp');
+});
+afterEach(() => {
+ vi.unstubAllEnvs();
+ _resetMemoryRootCache();
+ rmSync(root, { recursive: true, force: true });
+});
+it('default CLI snapshots both active sibling stores', async () => {
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(root, '.swarm', 'backups'))).toEqual(['default-cli', 'default-mcp']);
+});
+it('explicit --db retains one source even when DB environment overrides are set', async () => {
+ vi.stubEnv('CLAUDE_FLOW_DB_PATH', join(root, '.swarm', 'memory.db'));
+ expect((await backup('--db', join(configured, 'agentdb-memory.db')))?.success).toBe(true);
+ expect(keys(join(configured, 'backups'))).toEqual(['configured-mcp']);
+});
+it.each([
+ ['claude-flow.config.json', 'memory.persistPath'],
+ ['.claude-flow/config.json', 'memory.path'],
+])('uses actual CLI-produced %s %s with relative paths', async (location, key) => {
+ await configure(location, key);
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(configured, 'backups'))).toEqual(['configured-cli', 'configured-mcp']);
+});
+it('directory environment override takes precedence over the CLI config', async () => {
+ await configure('claude-flow.config.json', 'memory.persistPath');
+ vi.stubEnv('CLAUDE_FLOW_MEMORY_PATH', join(root, '.swarm'));
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(root, '.swarm', 'backups'))).toEqual(['default-cli', 'default-mcp']);
+});
+it('full-file DB environment override selects only that source', async () => {
+ await configure('claude-flow.config.json', 'memory.persistPath');
+ seed(configured, 'cli-override.db', 'override-cli');
+ vi.stubEnv('CLAUDE_FLOW_DB_PATH', join(configured, 'cli-override.db'));
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(configured, 'backups'))).toEqual(['override-cli']);
+});
+it('a same-basename DB override stays single-store in an explicit shared destination', async () => {
+ seed(join(root, 'outside'), 'agentdb-memory.db', 'outside-override');
+ vi.stubEnv('CLAUDE_FLOW_DB_PATH', join(root, 'outside', 'agentdb-memory.db'));
+ const dir = join(root, 'shared-backups');
+ expect((await backup('--dir', dir))?.success).toBe(true);
+ expect(keys(dir)).toEqual(['outside-override']);
+ expect(keys(configured)).toEqual(['configured-cli', 'configured-mcp']);
+});
+it('both default stores retain separate snapshot sets in an explicit shared destination', async () => {
+ const dir = join(root, 'shared-backups');
+ const result = await backup('--dir', dir, '--keep', '1');
+ expect(result?.success).toBe(true);
+ expect(keys(dir)).toEqual(['default-cli', 'default-mcp']);
+});
+it.each([false, true])('public daemon trigger snapshots the active pair (configured=%s)', async useConfig => {
+ if (useConfig) await configure('claude-flow.config.json', 'memory.persistPath');
+ const daemon = new WorkerDaemon(root, { aiWorkersEnabled: false });
+ try {
+ const result = await daemon.triggerWorker('backup');
+ expect(result.success).toBe(true);
+ const dir = useConfig ? configured : join(root, '.swarm');
+ expect(keys(join(dir, 'backups'))).toEqual(useConfig ? ['configured-cli', 'configured-mcp'] : ['default-cli', 'default-mcp']);
+ const metrics = JSON.parse(readFileSync(join(root, '.claude-flow', 'metrics', 'backup.json'), 'utf8'));
+ expect(metrics.backedUp).toBe(true);
+ expect(metrics.backups.filter((receipt: { backedUp: boolean }) => receipt.backedUp)).toHaveLength(2);
+ } finally { await daemon.stop(); }
+});
+it('an absent primary does not hide an existing AgentDB store', async () => {
+ rmSync(join(root, '.swarm', 'memory.db'));
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(root, '.swarm', 'backups'))).toEqual(['default-mcp']);
+});
+it('absent sibling and entirely absent stores retain benign no-db behavior', async () => {
+ rmSync(join(root, '.swarm', 'agentdb-memory.db'));
+ expect((await backup())?.success).toBe(true);
+ expect(keys(join(root, '.swarm', 'backups'))).toEqual(['default-cli']);
+ rmSync(join(root, '.swarm', 'memory.db'));
+ const result = await backup();
+ expect(result?.success).toBe(true);
+ expect(result?.data).toMatchObject({ backedUp: false, skipped: 'no-db' });
+});
+it('a present unbackuppable sibling fails the aggregate while retaining successful receipts', async () => {
+ rmSync(join(root, '.swarm', 'agentdb-memory.db'));
+ mkdirSync(join(root, '.swarm', 'agentdb-memory.db'));
+ const result = await backup();
+ expect(result?.success).toBe(false);
+ expect(result?.data).toMatchObject({ backedUp: false });
+ const receipts = (result?.data as { backups: Array<{ dbPath: string; backedUp: boolean }> }).backups;
+ expect(receipts).toEqual(expect.arrayContaining([
+ expect.objectContaining({ dbPath: join(root, '.swarm', 'memory.db'), backedUp: true }),
+ expect.objectContaining({ dbPath: join(root, '.swarm', 'agentdb-memory.db'), backedUp: false }),
+ ]));
+});
+it('canonical cached root and reset preserve their existing environment semantics', () => {
+ vi.stubEnv('CLAUDE_FLOW_MEMORY_PATH', configured);
+ expect(getMemoryRoot()).toBe(configured);
+ vi.stubEnv('CLAUDE_FLOW_MEMORY_PATH', join(root, '.swarm'));
+ expect(getMemoryRoot()).toBe(configured);
+ _resetMemoryRootCache();
+ expect(getMemoryRoot()).toBe(join(root, '.swarm'));
+});
diff --git a/v3/@claude-flow/cli/src/commands/memory-backup.ts b/v3/@claude-flow/cli/src/commands/memory-backup.ts
index c03e105366..b4b1877df9 100644
--- a/v3/@claude-flow/cli/src/commands/memory-backup.ts
+++ b/v3/@claude-flow/cli/src/commands/memory-backup.ts
@@ -1,42 +1,52 @@
/**
* V3 CLI `memory backup` command.
*
- * WAL-safe snapshot of the vector-memory DB (`.swarm/memory.db`) with rotation
+ * WAL-safe snapshots of the active CLI and AgentDB stores 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';
+import { backupMemoryDb, backupProjectMemoryDbs, type BackupResult } 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',
+ description: 'Snapshot active project memory stores β€” WAL-safe, rotated, optional GCS offsite',
options: [
- { name: 'db', description: 'Source DB (default: .swarm/memory.db)', type: 'string' },
+ { name: 'db', description: 'Source DB (default: configured CLI and AgentDB stores)', 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', description: 'Snapshot active project stores, 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),
+ const options = {
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,
- });
+ };
+ const explicitDb = ctx.flags.db as string | undefined;
+ let r: BackupResult;
+ let receipts: BackupResult[];
+ if (explicitDb) {
+ r = await backupMemoryDb({ ...options, dbPath: explicitDb });
+ receipts = [r];
+ } else {
+ const project = await backupProjectMemoryDbs(ctx.cwd, options);
+ r = project;
+ receipts = project.backups;
+ }
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.');
+ output.printWarning('No memory DB found to back up. Nothing to do.');
return { success: true, data: r };
}
output.printError(`Backup skipped: ${r.skipped}`);
@@ -44,7 +54,9 @@ export const backupCommand: Command = {
}
output.writeln();
- output.writeln(output.success(`Backed up β†’ ${r.path}`));
+ for (const receipt of receipts) {
+ if (receipt.backedUp) output.writeln(output.success(`Backed up β†’ ${receipt.path}`));
+ }
output.printList([
`Size: ${Math.round((r.sizeBytes ?? 0) / 1024)} KB`,
`Rotated: ${r.rotatedAway?.length ?? 0} old snapshot(s) removed`,
diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
index 72584961bc..9bf6eb7797 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -10,6 +10,7 @@
*/
import { loadBetterSqlite3 } from './shared-sqlite.js';
+import { resolveMemoryRoot } from './memory-root.js';
import { liveMemoryRowSql } from './live-memory-row.js';
import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS, type EmbeddingQ8 } from './embedding-q8.js';
import * as fs from 'fs';
@@ -126,35 +127,7 @@ async function releaseOwnNativeHandle(dbPath: string): Promise<void> {
let _memoryRootCache: string | undefined;
export function getMemoryRoot(): string {
if (_memoryRootCache !== undefined) return _memoryRootCache;
-
- // 1. Env var
- const envPath = process.env.CLAUDE_FLOW_MEMORY_PATH;
- if (envPath && envPath.trim().length > 0) {
- _memoryRootCache = path.resolve(envPath);
- return _memoryRootCache;
- }
-
- // 2. Config file (claude-flow.config.json)
- const configCandidates = [
- path.resolve(process.cwd(), 'claude-flow.config.json'),
- path.resolve(process.cwd(), '.claude-flow', 'config.json'),
- ];
- for (const configPath of configCandidates) {
- if (!fs.existsSync(configPath)) continue;
- try {
- const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
- const fromConfig: unknown = raw?.memory?.persistPath ?? raw?.memory?.path;
- if (typeof fromConfig === 'string' && fromConfig.trim().length > 0) {
- _memoryRootCache = path.resolve(fromConfig);
- return _memoryRootCache;
- }
- } catch {
- /* malformed config β€” fall through to default */
- }
- }
-
- // 3. Default
- _memoryRootCache = path.resolve(process.cwd(), '.swarm');
+ _memoryRootCache = resolveMemoryRoot(process.cwd());
return _memoryRootCache;
}
diff --git a/v3/@claude-flow/cli/src/memory/memory-root.ts b/v3/@claude-flow/cli/src/memory/memory-root.ts
new file mode 100644
index 0000000000..73f079f887
--- /dev/null
+++ b/v3/@claude-flow/cli/src/memory/memory-root.ts
@@ -0,0 +1,26 @@
+/** Uncached memory-directory authority for an explicit project directory. */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function resolveMemoryRoot(cwd: string): string {
+ const envPath = process.env.CLAUDE_FLOW_MEMORY_PATH;
+ if (envPath && envPath.trim().length > 0) return path.resolve(cwd, envPath);
+
+ const configCandidates = [
+ path.resolve(cwd, 'claude-flow.config.json'),
+ path.resolve(cwd, '.claude-flow', 'config.json'),
+ ];
+ for (const configPath of configCandidates) {
+ if (!fs.existsSync(configPath)) continue;
+ try {
+ const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+ const fromConfig: unknown = raw?.memory?.persistPath ?? raw?.memory?.path;
+ if (typeof fromConfig === 'string' && fromConfig.trim().length > 0) {
+ return path.resolve(cwd, fromConfig);
+ }
+ } catch {
+ /* malformed config β€” fall through to default */
+ }
+ }
+ return path.resolve(cwd, '.swarm');
+}
diff --git a/v3/@claude-flow/cli/src/services/memory-backup.ts b/v3/@claude-flow/cli/src/services/memory-backup.ts
index 06e584ad72..f6663bb159 100644
--- a/v3/@claude-flow/cli/src/services/memory-backup.ts
+++ b/v3/@claude-flow/cli/src/services/memory-backup.ts
@@ -15,6 +15,7 @@
import * as fs from 'fs';
import * as path from 'path';
import { readFileMaybeEncrypted } from '../fs-secure.js';
+import { resolveMemoryRoot } from '../memory/memory-root.js';
export interface BackupOptions {
/** Source DB (default: <cwd>/.swarm/memory.db). */
@@ -43,6 +44,39 @@ export function defaultMemoryDbPath(cwd: string = process.cwd()): string {
return path.join(cwd, '.swarm', 'memory.db');
}
+export interface ProjectBackupResult extends BackupResult {
+ backups: Array<BackupResult & { dbPath: string }>;
+}
+
+/** Back up the active project stores; an explicit full-file override stays single-store. */
+export async function backupProjectMemoryDbs(
+ cwd: string,
+ opts: Omit<BackupOptions, 'dbPath'> = {},
+): Promise<ProjectBackupResult> {
+ const override = process.env.CLAUDE_FLOW_DB_PATH;
+ let sources: string[];
+ if (override && override.trim().length > 0) {
+ sources = [path.resolve(cwd, override)];
+ } else {
+ const root = resolveMemoryRoot(cwd);
+ sources = [path.join(root, 'memory.db'), path.join(root, 'agentdb-memory.db')];
+ }
+ const backups: ProjectBackupResult['backups'] = [];
+ for (const dbPath of sources) {
+ backups.push({ ...await backupMemoryDb({ ...opts, dbPath }), dbPath });
+ }
+ const successful = backups.filter(result => result.backedUp);
+ const failed = backups.find(result => !result.backedUp && result.skipped !== 'no-db');
+ return {
+ ...successful[0],
+ backedUp: successful.length > 0 && !failed,
+ sizeBytes: successful.reduce((sum, result) => sum + (result.sizeBytes ?? 0), 0),
+ rotatedAway: successful.flatMap(result => result.rotatedAway ?? []),
+ skipped: failed?.skipped ?? (successful.length === 0 ? 'no-db' : undefined),
+ backups,
+ };
+}
+
/** ISO timestamp safe for filenames (no ':' or '.'). */
function fileStamp(ms: number): string {
return new Date(ms).toISOString().replace(/[:.]/g, '-');
diff --git a/v3/@claude-flow/cli/src/services/worker-daemon.ts b/v3/@claude-flow/cli/src/services/worker-daemon.ts
index 2bcb490eb1..9f22077364 100644
--- a/v3/@claude-flow/cli/src/services/worker-daemon.ts
+++ b/v3/@claude-flow/cli/src/services/worker-daemon.ts
@@ -32,7 +32,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';
+import { backupProjectMemoryDbs } from './memory-backup.js';
import { resolveGitWorkspaceIdentity, type GitWorkspaceIdentity } from './git-workspace-identity.js';
import { getWorkspaceLeaseRegistry } from './workspace-lease.js';
import { getRepoSupervisorRegistry, type SupervisorRecord } from './repo-supervisor.js';
@@ -1837,8 +1837,8 @@ export class WorkerDaemon extends EventEmitter {
}
/**
- * 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
+ * Nightly memory-DB backup worker (24h interval). Takes WAL-safe, consistent
+ * snapshots of the active CLI and AgentDB stores 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.
@@ -1851,14 +1851,14 @@ export class WorkerDaemon extends EventEmitter {
let result: Record<string, unknown>;
try {
const keepEnv = Number(process.env.RUFLO_BACKUP_KEEP);
- const r = await backupMemoryDb({
- dbPath: defaultMemoryDbPath(this.projectRoot),
+ const r = await backupProjectMemoryDbs(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,
+ backups: r.backups,
path: r.path,
sizeBytes: r.sizeBytes ?? 0,
rotatedAway: r.rotatedAway?.length ?? 0,