π 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
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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,