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(ADR-057): RVF native storage with security hardening (#1244)

rUvdc8463872da6
diff --git a/tests/rvf-backend.test.ts b/tests/rvf-backend.test.ts
new file mode 100644
index 0000000000..2b1869c3a2
--- /dev/null
+++ b/tests/rvf-backend.test.ts
@@ -0,0 +1,548 @@
+import { describe, it, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RvfBackend } from '../v3/@claude-flow/memory/src/rvf-backend.js';
+import type {
+ MemoryEntry,
+ MemoryQuery,
+ SearchOptions,
+ IMemoryBackend,
+} from '../v3/@claude-flow/memory/src/types.js';
+
+// -- Helpers --
+
+function makeTmpDir(): string {
+ return mkdtempSync(join(tmpdir(), 'rvf-test-'));
+}
+
+function makeEntry(overrides: Partial<MemoryEntry> = {}): MemoryEntry {
+ const now = Date.now();
+ return {
+ id: `e-${Math.random().toString(36).slice(2, 10)}`,
+ key: 'test-key',
+ content: 'test content',
+ type: 'semantic',
+ namespace: 'default',
+ tags: [],
+ metadata: {},
+ accessLevel: 'private',
+ createdAt: now,
+ updatedAt: now,
+ version: 1,
+ references: [],
+ accessCount: 0,
+ lastAccessedAt: now,
+ ...overrides,
+ };
+}
+
+function randomVec(dim = 4): Float32Array {
+ const v = new Float32Array(dim);
+ for (let i = 0; i < dim; i++) v[i] = Math.random() - 0.5;
+ // normalise so cosine is meaningful
+ const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+ if (norm > 0) for (let i = 0; i < dim; i++) v[i] /= norm;
+ return v;
+}
+
+// -- Tests --
+
+describe('RvfBackend', () => {
+ let tmpDir: string;
+ let backend: RvfBackend;
+
+ beforeEach(async () => {
+ tmpDir = makeTmpDir();
+ backend = new RvfBackend({
+ databasePath: join(tmpDir, 'test.rvf'),
+ dimensions: 4,
+ autoPersistInterval: 0, // disable timer in tests
+ });
+ await backend.initialize();
+ });
+
+ afterEach(async () => {
+ try { await backend.shutdown(); } catch {}
+ try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+ });
+
+ // ---- 1. Constructor & Config ----
+ describe('constructor & config', () => {
+ it('should apply default config values', async () => {
+ const b = new RvfBackend({ databasePath: ':memory:' });
+ await b.initialize();
+ const stats = await b.getStats();
+ assert.equal(stats.totalEntries, 0);
+ await b.shutdown();
+ });
+
+ it('should accept custom dimensions and metric', async () => {
+ const b = new RvfBackend({
+ databasePath: ':memory:',
+ dimensions: 8,
+ metric: 'dot',
+ });
+ await b.initialize();
+ const health = await b.healthCheck();
+ assert.equal(health.status, 'healthy');
+ await b.shutdown();
+ });
+ });
+
+ // ---- 2. Initialize / Shutdown ----
+ describe('initialize & shutdown', () => {
+ it('should be idempotent on double init', async () => {
+ await backend.initialize(); // second call
+ const stats = await backend.getStats();
+ assert.equal(stats.totalEntries, 0);
+ });
+
+ it('should persist file on shutdown when dirty', async () => {
+ await backend.store(makeEntry());
+ await backend.shutdown();
+ assert.ok(existsSync(join(tmpDir, 'test.rvf')));
+ });
+
+ it('should reload entries after shutdown + reinit', async () => {
+ const entry = makeEntry({ id: 'persist-1', key: 'k1' });
+ await backend.store(entry);
+ await backend.shutdown();
+
+ const b2 = new RvfBackend({
+ databasePath: join(tmpDir, 'test.rvf'),
+ dimensions: 4,
+ autoPersistInterval: 0,
+ });
+ await b2.initialize();
+ const got = await b2.get('persist-1');
+ assert.ok(got);
+ assert.equal(got.key, 'k1');
+ assert.equal(got.content, entry.content);
+ await b2.shutdown();
+ });
+
+ it('should be a no-op when shutdown is called before init', async () => {
+ const b = new RvfBackend({ databasePath: ':memory:' });
+ await b.shutdown(); // should not throw
+ });
+ });
+
+ // ---- 3. CRUD ----
+ describe('CRUD operations', () => {
+ it('store and get by id', async () => {
+ const entry = makeEntry({ id: 'crud-1' });
+ await backend.store(entry);
+ const got = await backend.get('crud-1');
+ assert.ok(got);
+ assert.equal(got.id, 'crud-1');
+ });
+
+ it('get returns null for missing id', async () => {
+ const got = await backend.get('nonexistent');
+ assert.equal(got, null);
+ });
+
+ it('get increments accessCount', async () => {
+ await backend.store(makeEntry({ id: 'ac-1', accessCount: 0 }));
+ await backend.get('ac-1');
+ const got = await backend.get('ac-1');
+ assert.ok(got);
+ assert.equal(got.accessCount, 2);
+ });
+
+ it('getByKey retrieves by namespace + key', async () => {
+ await backend.store(makeEntry({ id: 'bk-1', namespace: 'ns1', key: 'mykey' }));
+ const got = await backend.getByKey('ns1', 'mykey');
+ assert.ok(got);
+ assert.equal(got.id, 'bk-1');
+ });
+
+ it('getByKey returns null for wrong namespace', async () => {
+ await backend.store(makeEntry({ namespace: 'ns1', key: 'mykey' }));
+ assert.equal(await backend.getByKey('ns2', 'mykey'), null);
+ });
+
+ it('update modifies entry and bumps version', async () => {
+ await backend.store(makeEntry({ id: 'up-1', content: 'old', version: 1 }));
+ const updated = await backend.update('up-1', { content: 'new' });
+ assert.ok(updated);
+ assert.equal(updated.content, 'new');
+ assert.equal(updated.version, 2);
+ });
+
+ it('update returns null for missing id', async () => {
+ assert.equal(await backend.update('missing', { content: 'x' }), null);
+ });
+
+ it('delete removes entry and returns true', async () => {
+ await backend.store(makeEntry({ id: 'del-1' }));
+ assert.equal(await backend.delete('del-1'), true);
+ assert.equal(await backend.get('del-1'), null);
+ });
+
+ it('delete returns false for missing id', async () => {
+ assert.equal(await backend.delete('missing'), false);
+ });
+ });
+
+ // ---- 4. Query ----
+ describe('query', () => {
+ beforeEach(async () => {
+ await backend.bulkInsert([
+ makeEntry({ id: 'q1', namespace: 'alpha', key: 'a1', type: 'episodic', tags: ['urgent'], createdAt: 1000, updatedAt: 1000 }),
+ makeEntry({ id: 'q2', namespace: 'alpha', key: 'a2', type: 'semantic', tags: ['urgent', 'bug'], createdAt: 2000, updatedAt: 2000 }),
+ makeEntry({ id: 'q3', namespace: 'beta', key: 'b1', type: 'semantic', tags: [], createdAt: 3000, updatedAt: 3000 }),
+ makeEntry({ id: 'q4', namespace: 'beta', key: 'prefix-abc', type: 'procedural', tags: ['bug'], createdAt: 4000, updatedAt: 4000 }),
+ ]);
+ });
+
+ it('filters by namespace', async () => {
+ const r = await backend.query({ type: 'exact', namespace: 'alpha', limit: 10 });
+ assert.equal(r.length, 2);
+ assert.ok(r.every(e => e.namespace === 'alpha'));
+ });
+
+ it('filters by tags (AND logic)', async () => {
+ const r = await backend.query({ type: 'tag', tags: ['urgent', 'bug'], limit: 10 });
+ assert.equal(r.length, 1);
+ assert.equal(r[0].id, 'q2');
+ });
+
+ it('filters by memoryType', async () => {
+ const r = await backend.query({ type: 'exact', memoryType: 'procedural', limit: 10 });
+ assert.equal(r.length, 1);
+ assert.equal(r[0].id, 'q4');
+ });
+
+ it('filters by keyPrefix', async () => {
+ const r = await backend.query({ type: 'prefix', keyPrefix: 'prefix-', limit: 10 });
+ assert.equal(r.length, 1);
+ assert.equal(r[0].id, 'q4');
+ });
+
+ it('filters by createdAfter / createdBefore', async () => {
+ const r = await backend.query({ type: 'exact', createdAfter: 1500, createdBefore: 3500, limit: 10 });
+ assert.equal(r.length, 2); // q2 (2000) and q3 (3000)
+ });
+
+ it('respects limit', async () => {
+ const r = await backend.query({ type: 'exact', limit: 2 });
+ assert.equal(r.length, 2);
+ });
+
+ it('respects offset', async () => {
+ const all = await backend.query({ type: 'exact', limit: 100 });
+ const page = await backend.query({ type: 'exact', limit: 100, offset: 2 });
+ assert.equal(page.length, all.length - 2);
+ });
+
+ it('excludes expired entries by default', async () => {
+ await backend.store(makeEntry({ id: 'exp-1', expiresAt: 1 })); // already expired
+ const r = await backend.query({ type: 'exact', limit: 100 });
+ assert.ok(!r.some(e => e.id === 'exp-1'));
+ });
+
+ it('includes expired entries when includeExpired is true', async () => {
+ await backend.store(makeEntry({ id: 'exp-2', expiresAt: 1 }));
+ const r = await backend.query({ type: 'exact', limit: 100, includeExpired: true });
+ assert.ok(r.some(e => e.id === 'exp-2'));
+ });
+ });
+
+ // ---- 5. Search ----
+ describe('search', () => {
+ it('finds similar vectors via cosine similarity', async () => {
+ const target = new Float32Array([1, 0, 0, 0]);
+ const similar = new Float32Array([0.9, 0.1, 0, 0]);
+ const dissimilar = new Float32Array([0, 0, 0, 1]);
+
+ await backend.store(makeEntry({ id: 's1', embedding: similar }));
+ await backend.store(makeEntry({ id: 's2', embedding: dissimilar }));
+
+ const results = await backend.search(target, { k: 2 });
+ assert.ok(results.length >= 1);
+ assert.equal(results[0].entry.id, 's1');
+ assert.ok(results[0].score > results[results.length - 1].score);
+ });
+
+ it('applies threshold filtering', async () => {
+ await backend.store(makeEntry({ id: 'th1', embedding: new Float32Array([1, 0, 0, 0]) }));
+ await backend.store(makeEntry({ id: 'th2', embedding: new Float32Array([0, 0, 0, 1]) }));
+
+ const results = await backend.search(new Float32Array([1, 0, 0, 0]), {
+ k: 10,
+ threshold: 0.9,
+ });
+ assert.equal(results.length, 1);
+ assert.equal(results[0].entry.id, 'th1');
+ });
+
+ it('filters by namespace in search', async () => {
+ const vec = new Float32Array([1, 0, 0, 0]);
+ await backend.store(makeEntry({ id: 'ns1', namespace: 'keep', embedding: vec }));
+ await backend.store(makeEntry({ id: 'ns2', namespace: 'skip', embedding: vec }));
+
+ const results = await backend.search(vec, {
+ k: 10,
+ filters: { type: 'exact', limit: 10, namespace: 'keep' },
+ });
+ assert.ok(results.every(r => r.entry.namespace === 'keep'));
+ });
+
+ it('limits results to k', async () => {
+ for (let i = 0; i < 5; i++) {
+ await backend.store(makeEntry({ id: `k${i}`, embedding: randomVec() }));
+ }
+ const results = await backend.search(randomVec(), { k: 2 });
+ assert.ok(results.length <= 2);
+ });
+
+ it('returns empty for empty database', async () => {
+ const results = await backend.search(randomVec(), { k: 5 });
+ assert.equal(results.length, 0);
+ });
+ });
+
+ // ---- 6. Bulk Operations ----
+ describe('bulk operations', () => {
+ it('bulkInsert stores multiple entries', async () => {
+ const entries = Array.from({ length: 5 }, (_, i) =>
+ makeEntry({ id: `bulk-${i}`, key: `k${i}` })
+ );
+ await backend.bulkInsert(entries);
+ assert.equal(await backend.count(), 5);
+ });
+
+ it('bulkDelete removes specified entries', async () => {
+ await backend.bulkInsert([
+ makeEntry({ id: 'bd-1' }),
+ makeEntry({ id: 'bd-2' }),
+ makeEntry({ id: 'bd-3' }),
+ ]);
+ const deleted = await backend.bulkDelete(['bd-1', 'bd-3', 'nonexistent']);
+ assert.equal(deleted, 2);
+ assert.equal(await backend.count(), 1);
+ assert.ok(await backend.get('bd-2'));
+ });
+ });
+
+ // ---- 7. Namespace Operations ----
+ describe('namespace operations', () => {
+ beforeEach(async () => {
+ await backend.bulkInsert([
+ makeEntry({ id: 'n1', namespace: 'a', key: 'k1' }),
+ makeEntry({ id: 'n2', namespace: 'a', key: 'k2' }),
+ makeEntry({ id: 'n3', namespace: 'b', key: 'k3' }),
+ ]);
+ });
+
+ it('count without namespace returns total', async () => {
+ assert.equal(await backend.count(), 3);
+ });
+
+ it('count with namespace returns filtered count', async () => {
+ assert.equal(await backend.count('a'), 2);
+ assert.equal(await backend.count('b'), 1);
+ assert.equal(await backend.count('empty'), 0);
+ });
+
+ it('listNamespaces returns all unique namespaces', async () => {
+ const ns = await backend.listNamespaces();
+ assert.deepEqual(ns.sort(), ['a', 'b']);
+ });
+
+ it('clearNamespace removes only that namespace', async () => {
+ const cleared = await backend.clearNamespace('a');
+ assert.equal(cleared, 2);
+ assert.equal(await backend.count(), 1);
+ assert.ok(await backend.get('n3'));
+ });
+ });
+
+ // ---- 8. Persistence & Binary Format ----
+ describe('persistence', () => {
+ it('persisted file starts with RVF magic bytes', async () => {
+ await backend.store(makeEntry({ id: 'magic-1' }));
+ await backend.shutdown();
+
+ const buf = readFileSync(join(tmpDir, 'test.rvf'));
+ assert.equal(buf[0], 0x52); // R
+ assert.equal(buf[1], 0x56); // V
+ assert.equal(buf[2], 0x46); // F
+ assert.equal(buf[3], 0x00); // \0
+ });
+
+ it('embeddings survive round-trip', async () => {
+ const vec = new Float32Array([0.1, 0.2, 0.3, 0.4]);
+ await backend.store(makeEntry({ id: 'emb-1', embedding: vec }));
+ await backend.shutdown();
+
+ const b2 = new RvfBackend({
+ databasePath: join(tmpDir, 'test.rvf'),
+ dimensions: 4,
+ autoPersistInterval: 0,
+ });
+ await b2.initialize();
+ const got = await b2.get('emb-1');
+ assert.ok(got?.embedding);
+ for (let i = 0; i < 4; i++) {
+ assert.ok(Math.abs(got.embedding[i] - vec[i]) < 1e-6);
+ }
+ await b2.shutdown();
+ });
+
+ it(':memory: path does not create a file', async () => {
+ const b = new RvfBackend({ databasePath: ':memory:', dimensions: 4 });
+ await b.initialize();
+ await b.store(makeEntry());
+ await b.shutdown();
+ // no file should be created anywhere for :memory:
+ });
+ });
+
+ // ---- 9. HNSW Index ----
+ describe('HNSW index', () => {
+ it('search reflects added and removed vectors', async () => {
+ const vec = new Float32Array([1, 0, 0, 0]);
+ await backend.store(makeEntry({ id: 'h1', embedding: vec }));
+
+ let results = await backend.search(vec, { k: 5 });
+ assert.ok(results.some(r => r.entry.id === 'h1'));
+
+ await backend.delete('h1');
+ results = await backend.search(vec, { k: 5 });
+ assert.ok(!results.some(r => r.entry.id === 'h1'));
+ });
+
+ it('indexes vectors from bulkInsert', async () => {
+ const entries = Array.from({ length: 3 }, (_, i) =>
+ makeEntry({ id: `bi-${i}`, embedding: randomVec() })
+ );
+ await backend.bulkInsert(entries);
+
+ const results = await backend.search(entries[0].embedding!, { k: 10 });
+ assert.ok(results.length > 0);
+ });
+ });
+
+ // ---- 10. Stats & Health ----
+ describe('stats & health', () => {
+ it('getStats returns correct counts', async () => {
+ await backend.bulkInsert([
+ makeEntry({ id: 'st1', namespace: 'x', type: 'episodic', content: 'abc' }),
+ makeEntry({ id: 'st2', namespace: 'x', type: 'semantic', content: 'def' }),
+ makeEntry({ id: 'st3', namespace: 'y', type: 'episodic', content: 'ghi' }),
+ ]);
+ const stats = await backend.getStats();
+ assert.equal(stats.totalEntries, 3);
+ assert.equal(stats.entriesByNamespace['x'], 2);
+ assert.equal(stats.entriesByNamespace['y'], 1);
+ assert.equal(stats.entriesByType['episodic'], 2);
+ assert.equal(stats.entriesByType['semantic'], 1);
+ assert.ok(stats.memoryUsage > 0);
+ });
+
+ it('getStats includes HNSW stats when vectors present', async () => {
+ await backend.store(makeEntry({ embedding: randomVec() }));
+ const stats = await backend.getStats();
+ assert.ok(stats.hnswStats);
+ assert.equal(stats.hnswStats.vectorCount, 1);
+ });
+
+ it('healthCheck returns healthy after init', async () => {
+ const health = await backend.healthCheck();
+ assert.equal(health.status, 'healthy');
+ assert.ok(health.timestamp > 0);
+ assert.equal(health.issues.length, 0);
+ });
+
+ it('healthCheck returns unhealthy before init', async () => {
+ const b = new RvfBackend({ databasePath: ':memory:', dimensions: 4 });
+ const health = await b.healthCheck();
+ assert.equal(health.status, 'unhealthy');
+ assert.ok(health.issues.length > 0);
+ });
+ });
+
+ // ---- 11. Edge Cases ----
+ describe('edge cases', () => {
+ it('handles empty database gracefully', async () => {
+ assert.equal(await backend.count(), 0);
+ assert.deepEqual(await backend.listNamespaces(), []);
+ assert.deepEqual(await backend.query({ type: 'exact', limit: 10 }), []);
+ const stats = await backend.getStats();
+ assert.equal(stats.totalEntries, 0);
+ });
+
+ it('init with missing file dir creates it on persist', async () => {
+ const deepPath = join(tmpDir, 'sub', 'dir', 'deep.rvf');
+ const b = new RvfBackend({
+ databasePath: deepPath,
+ dimensions: 4,
+ autoPersistInterval: 0,
+ });
+ await b.initialize();
+ await b.store(makeEntry());
+ await b.shutdown();
+ assert.ok(existsSync(deepPath));
+ });
+
+ it('handles corrupt file without crashing', async () => {
+ const path = join(tmpDir, 'corrupt.rvf');
+ const { writeFileSync } = await import('node:fs');
+ writeFileSync(path, Buffer.from('RVF\0garbage data here'));
+
+ const b = new RvfBackend({
+ databasePath: path,
+ dimensions: 4,
+ autoPersistInterval: 0,
+ });
+ // should not throw - gracefully handles corrupt data
+ await b.initialize();
+ assert.equal(await b.count(), 0);
+ await b.shutdown();
+ });
+
+ it('store overwrites entry with same id', async () => {
+ await backend.store(makeEntry({ id: 'ow-1', content: 'first' }));
+ await backend.store(makeEntry({ id: 'ow-1', content: 'second' }));
+ const got = await backend.get('ow-1');
+ assert.equal(got?.content, 'second');
+ });
+ });
+
+ // ---- 12. IMemoryBackend Interface Conformance ----
+ describe('IMemoryBackend conformance', () => {
+ it('implements all required interface methods', () => {
+ const requiredMethods: (keyof IMemoryBackend)[] = [
+ 'initialize', 'shutdown', 'store', 'get', 'getByKey',
+ 'update', 'delete', 'query', 'search', 'bulkInsert',
+ 'bulkDelete', 'count', 'listNamespaces', 'clearNamespace',
+ 'getStats', 'healthCheck',
+ ];
+ for (const method of requiredMethods) {
+ assert.equal(typeof (backend as any)[method], 'function', `missing method: ${method}`);
+ }
+ });
+
+ it('all methods return promises', async () => {
+ const entry = makeEntry({ id: 'iface-1' });
+ assert.ok(backend.store(entry) instanceof Promise);
+ assert.ok(backend.get('x') instanceof Promise);
+ assert.ok(backend.getByKey('ns', 'k') instanceof Promise);
+ assert.ok(backend.update('x', {}) instanceof Promise);
+ assert.ok(backend.delete('x') instanceof Promise);
+ assert.ok(backend.query({ type: 'exact', limit: 1 }) instanceof Promise);
+ assert.ok(backend.search(randomVec(), { k: 1 }) instanceof Promise);
+ assert.ok(backend.bulkInsert([]) instanceof Promise);
+ assert.ok(backend.bulkDelete([]) instanceof Promise);
+ assert.ok(backend.count() instanceof Promise);
+ assert.ok(backend.listNamespaces() instanceof Promise);
+ assert.ok(backend.clearNamespace('x') instanceof Promise);
+ assert.ok(backend.getStats() instanceof Promise);
+ assert.ok(backend.healthCheck() instanceof Promise);
+ });
+ });
+});
diff --git a/tests/rvf-capability-verify.test.ts b/tests/rvf-capability-verify.test.ts
new file mode 100644
index 0000000000..bb3f1a8ef2
--- /dev/null
+++ b/tests/rvf-capability-verify.test.ts
@@ -0,0 +1,848 @@
+/**
+ * RVF Comprehensive Capability Verification
+ *
+ * Tests EVERY capability across all RVF modules to confirm 100% functionality:
+ * 1. RvfBackend β€” IMemoryBackend contract (17 methods)
+ * 2. HnswLite β€” Vector search (add, remove, search, metrics)
+ * 3. RvfEventLog β€” Append-only event sourcing
+ * 4. RvfEmbeddingCache β€” Binary file cache with LRU/TTL
+ * 5. RvfEmbeddingService β€” Hash-based embedding generation
+ * 6. RvfLearningStore β€” SONA learning artifact persistence
+ * 7. PersistentSonaCoordinator β€” Pattern matching + learning loops
+ * 8. RvfMigrator β€” Bidirectional migration (JSON↔RVF, SQLite↔RVF)
+ * 9. Security β€” Path validation, input validation, atomic writes
+ * 10. Performance β€” Timer unref, safe iteration, no stack overflow
+ * 11. Forward/Backward compat β€” Binary format v1/v2
+ * 12. DatabaseProvider β€” Auto-selection of RVF backend
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync,
+ renameSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// --- Module Imports ---
+import { RvfBackend } from '../v3/@claude-flow/memory/src/rvf-backend.js';
+import type { RvfBackendConfig } from '../v3/@claude-flow/memory/src/rvf-backend.js';
+import { HnswLite, cosineSimilarity } from '../v3/@claude-flow/memory/src/hnsw-lite.js';
+import { RvfEventLog } from '../v3/@claude-flow/shared/src/events/rvf-event-log.js';
+import { RvfEmbeddingCache } from '../v3/@claude-flow/embeddings/src/rvf-embedding-cache.js';
+import { RvfEmbeddingService } from '../v3/@claude-flow/embeddings/src/rvf-embedding-service.js';
+import { RvfLearningStore } from '../v3/@claude-flow/memory/src/rvf-learning-store.js';
+import { PersistentSonaCoordinator } from '../v3/@claude-flow/memory/src/persistent-sona.js';
+import { RvfMigrator } from '../v3/@claude-flow/memory/src/rvf-migration.js';
+
+// --- Helpers ---
+let tmpDir: string;
+function tmp(name: string) { return join(tmpDir, name); }
+
+function makeEntry(id: string, ns = 'default', content = 'test') {
+ return {
+ id, key: `key-${id}`, content, type: 'semantic' as const,
+ namespace: ns, tags: ['tag1'], metadata: { source: 'test' },
+ accessLevel: 'private' as const, createdAt: Date.now(),
+ updatedAt: Date.now(), version: 1, references: [] as string[],
+ accessCount: 0, lastAccessedAt: Date.now(),
+ };
+}
+
+function makeEntryWithEmbedding(id: string, ns = 'default', content = 'test') {
+ const emb = new Float32Array(64);
+ for (let i = 0; i < 64; i++) emb[i] = Math.sin(i + id.charCodeAt(0));
+ return { ...makeEntry(id, ns, content), embedding: emb };
+}
+
+// =============================================================================
+// 1. RvfBackend β€” Full IMemoryBackend Contract
+// =============================================================================
+describe('1. RvfBackend β€” IMemoryBackend Contract', () => {
+ let backend: RvfBackend;
+
+ beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-cap-'));
+ backend = new RvfBackend({ databasePath: tmp('mem.rvf'), dimensions: 64 });
+ await backend.initialize();
+ });
+
+ afterEach(async () => {
+ await backend.shutdown();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('initialize + shutdown (idempotent)', async () => {
+ await backend.initialize(); // second call is no-op
+ await backend.shutdown();
+ await backend.shutdown(); // second call is no-op
+ });
+
+ it('store + get', async () => {
+ const entry = makeEntry('s1');
+ await backend.store(entry);
+ const result = await backend.get('s1');
+ assert.ok(result);
+ assert.equal(result.content, 'test');
+ });
+
+ it('getByKey', async () => {
+ await backend.store(makeEntry('gk1', 'ns'));
+ const result = await backend.getByKey('ns', 'key-gk1');
+ assert.ok(result);
+ assert.equal(result.id, 'gk1');
+ });
+
+ it('update', async () => {
+ await backend.store(makeEntry('u1'));
+ const updated = await backend.update('u1', { content: 'updated' });
+ assert.ok(updated);
+ assert.equal(updated.content, 'updated');
+ assert.equal(updated.version, 2);
+ });
+
+ it('delete', async () => {
+ await backend.store(makeEntry('d1'));
+ assert.equal(await backend.delete('d1'), true);
+ assert.equal(await backend.delete('d1'), false);
+ assert.equal(await backend.get('d1'), null);
+ });
+
+ it('query with filters', async () => {
+ await backend.store(makeEntry('q1', 'ns-a', 'alpha'));
+ await backend.store(makeEntry('q2', 'ns-b', 'beta'));
+ await backend.store(makeEntry('q3', 'ns-a', 'gamma'));
+
+ const results = await backend.query({ type: 'hybrid', namespace: 'ns-a', limit: 100 });
+ assert.equal(results.length, 2);
+ });
+
+ it('search with HNSW', async () => {
+ const e1 = makeEntryWithEmbedding('se1');
+ const e2 = makeEntryWithEmbedding('se2');
+ await backend.store(e1);
+ await backend.store(e2);
+
+ const results = await backend.search(e1.embedding, { k: 5 });
+ assert.ok(results.length > 0);
+ assert.equal(results[0].entry.id, 'se1'); // most similar to itself
+ });
+
+ it('bulkInsert + bulkDelete', async () => {
+ const entries = Array.from({ length: 20 }, (_, i) => makeEntry(`b${i}`));
+ await backend.bulkInsert(entries);
+ assert.equal(await backend.count(), 20);
+
+ const deleted = await backend.bulkDelete(['b0', 'b1', 'b2']);
+ assert.equal(deleted, 3);
+ assert.equal(await backend.count(), 17);
+ });
+
+ it('count + listNamespaces', async () => {
+ await backend.store(makeEntry('c1', 'ns-x'));
+ await backend.store(makeEntry('c2', 'ns-y'));
+ await backend.store(makeEntry('c3', 'ns-x'));
+
+ assert.equal(await backend.count(), 3);
+ assert.equal(await backend.count('ns-x'), 2);
+ const ns = await backend.listNamespaces();
+ assert.ok(ns.includes('ns-x'));
+ assert.ok(ns.includes('ns-y'));
+ });
+
+ it('clearNamespace', async () => {
+ await backend.store(makeEntry('cn1', 'clear-me'));
+ await backend.store(makeEntry('cn2', 'clear-me'));
+ await backend.store(makeEntry('cn3', 'keep'));
+
+ const cleared = await backend.clearNamespace('clear-me');
+ assert.equal(cleared, 2);
+ assert.equal(await backend.count(), 1);
+ });
+
+ it('getStats', async () => {
+ await backend.store(makeEntryWithEmbedding('st1'));
+ const stats = await backend.getStats();
+ assert.equal(stats.totalEntries, 1);
+ assert.ok(stats.memoryUsage > 0);
+ assert.ok(stats.hnswStats);
+ assert.equal(stats.hnswStats!.vectorCount, 1);
+ });
+
+ it('healthCheck', async () => {
+ const health = await backend.healthCheck();
+ assert.equal(health.status, 'healthy');
+ assert.ok(health.components.storage.status === 'healthy');
+ });
+
+ it('persistence across restart', async () => {
+ await backend.store(makeEntryWithEmbedding('p1', 'ns', 'persisted'));
+ await backend.shutdown();
+
+ // Re-open
+ const b2 = new RvfBackend({ databasePath: tmp('mem.rvf'), dimensions: 64 });
+ await b2.initialize();
+ const entry = await b2.get('p1');
+ assert.ok(entry);
+ assert.equal(entry.content, 'persisted');
+ assert.ok(entry.embedding);
+ assert.equal(entry.embedding!.length, 64);
+ await b2.shutdown();
+ });
+});
+
+// =============================================================================
+// 2. HnswLite β€” Vector Search
+// =============================================================================
+describe('2. HnswLite β€” Vector Search', () => {
+ it('add + search (cosine)', () => {
+ const hnsw = new HnswLite(4, 8, 50, 'cosine');
+ const v1 = new Float32Array([1, 0, 0, 0]);
+ const v2 = new Float32Array([0, 1, 0, 0]);
+ const v3 = new Float32Array([0.9, 0.1, 0, 0]);
+ hnsw.add('a', v1);
+ hnsw.add('b', v2);
+ hnsw.add('c', v3);
+ assert.equal(hnsw.size, 3);
+
+ const results = hnsw.search(v1, 2);
+ assert.equal(results[0].id, 'a'); // exact match
+ });
+
+ it('remove', () => {
+ const hnsw = new HnswLite(4, 8, 50, 'cosine');
+ hnsw.add('x', new Float32Array([1, 0, 0, 0]));
+ hnsw.remove('x');
+ assert.equal(hnsw.size, 0);
+ });
+
+ it('threshold filtering', () => {
+ const hnsw = new HnswLite(4, 8, 50, 'cosine');
+ hnsw.add('a', new Float32Array([1, 0, 0, 0]));
+ hnsw.add('b', new Float32Array([0, 1, 0, 0])); // orthogonal
+ const results = hnsw.search(new Float32Array([1, 0, 0, 0]), 10, 0.5);
+ assert.equal(results.length, 1); // only 'a' passes threshold
+ });
+
+ it('dot + euclidean metrics', () => {
+ const dot = new HnswLite(4, 8, 50, 'dot');
+ dot.add('a', new Float32Array([1, 0, 0, 0]));
+ const r1 = dot.search(new Float32Array([1, 0, 0, 0]), 1);
+ assert.ok(r1[0].score > 0);
+
+ const euc = new HnswLite(4, 8, 50, 'euclidean');
+ euc.add('a', new Float32Array([1, 0, 0, 0]));
+ const r2 = euc.search(new Float32Array([1, 0, 0, 0]), 1);
+ assert.ok(r2[0].score > 0);
+ });
+
+ it('cosineSimilarity function', () => {
+ const a = new Float32Array([1, 0]);
+ const b = new Float32Array([1, 0]);
+ assert.ok(Math.abs(cosineSimilarity(a, b) - 1.0) < 0.001);
+ const c = new Float32Array([0, 1]);
+ assert.ok(Math.abs(cosineSimilarity(a, c)) < 0.001);
+ });
+});
+
+// =============================================================================
+// 3. RvfEventLog β€” Append-Only Event Sourcing
+// =============================================================================
+describe('3. RvfEventLog β€” Event Sourcing', () => {
+ let log: RvfEventLog;
+
+ beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-ev-'));
+ log = new RvfEventLog({ logPath: tmp('events.rvf') });
+ await log.initialize();
+ });
+
+ afterEach(async () => {
+ await log.close();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('append + getEvents', async () => {
+ await log.append({
+ id: 'ev1', type: 'TaskCreated', aggregateId: 'agg-1',
+ aggregateType: 'Task', timestamp: Date.now(), version: 0, data: {},
+ });
+ const events = await log.getEvents('agg-1');
+ assert.equal(events.length, 1);
+ assert.equal(events[0].type, 'TaskCreated');
+ assert.equal(events[0].version, 1); // auto-incremented
+ });
+
+ it('getAllEvents with filters', async () => {
+ await log.append({
+ id: 'ev2', type: 'A', aggregateId: 'x',
+ aggregateType: 'T', timestamp: 1000, version: 0, data: {},
+ });
+ await log.append({
+ id: 'ev3', type: 'B', aggregateId: 'y',
+ aggregateType: 'T', timestamp: 2000, version: 0, data: {},
+ });
+ const filtered = await log.getAllEvents({ eventTypes: ['A'] });
+ assert.equal(filtered.length, 1);
+ assert.equal(filtered[0].id, 'ev2');
+ });
+
+ it('snapshots', async () => {
+ await log.saveSnapshot({ aggregateId: 'snap-1', version: 5, state: { x: 1 }, timestamp: Date.now() });
+ const snap = await log.getSnapshot('snap-1');
+ assert.ok(snap);
+ assert.equal(snap.version, 5);
+ });
+
+ it('getStats', async () => {
+ await log.append({
+ id: 'st1', type: 'T', aggregateId: 'a',
+ aggregateType: 'X', timestamp: Date.now(), version: 0, data: {},
+ });
+ const stats = await log.getStats();
+ assert.equal(stats.totalEvents, 1);
+ assert.equal(stats.snapshotCount, 0);
+ });
+
+ it('persistence across restart', async () => {
+ await log.append({
+ id: 'p1', type: 'Persisted', aggregateId: 'ag',
+ aggregateType: 'T', timestamp: Date.now(), version: 0, data: { key: 'value' },
+ });
+ await log.close();
+
+ const log2 = new RvfEventLog({ logPath: tmp('events.rvf') });
+ await log2.initialize();
+ const events = await log2.getEvents('ag');
+ assert.equal(events.length, 1);
+ assert.equal(events[0].type, 'Persisted');
+ assert.deepEqual(events[0].data, { key: 'value' });
+ await log2.close();
+ });
+
+ it('input validation rejects bad events', async () => {
+ await assert.rejects(
+ () => log.append({ id: 'bad', type: '', aggregateId: 'a', aggregateType: 'T', timestamp: 0, version: 0, data: {} }),
+ /valid type string/,
+ );
+ await assert.rejects(
+ () => log.append({ id: 'bad', type: 'T', aggregateId: '', aggregateType: 'T', timestamp: 0, version: 0, data: {} }),
+ /valid aggregateId string/,
+ );
+ });
+});
+
+// =============================================================================
+// 4. RvfEmbeddingCache β€” Binary File Cache
+// =============================================================================
+describe('4. RvfEmbeddingCache β€” Binary Cache', () => {
+ beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'rvf-ec-')); });
+ afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+ it('set + get + has + delete + size + clear', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('cache.rvec'), dimensions: 4 });
+ const emb = new Float32Array([1, 2, 3, 4]);
+ await cache.set('hello', emb);
+ assert.equal(await cache.size(), 1);
+ assert.equal(await cache.has('hello'), true);
+
+ const got = await cache.get('hello');
+ assert.ok(got);
+ assert.equal(got.length, 4);
+
+ assert.equal(await cache.delete('hello'), true);
+ assert.equal(await cache.size(), 0);
+
+ await cache.set('a', emb);
+ await cache.set('b', emb);
+ await cache.clear();
+ assert.equal(await cache.size(), 0);
+ await cache.close();
+ });
+
+ it('LRU eviction', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('lru.rvec'), maxSize: 5, dimensions: 2 });
+ for (let i = 0; i < 10; i++) {
+ await cache.set(`item-${i}`, new Float32Array([i, i]));
+ }
+ const size = await cache.size();
+ assert.ok(size <= 5, `Expected <=5 entries, got ${size}`);
+ await cache.close();
+ });
+
+ it('TTL expiration', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('ttl.rvec'), ttlMs: 1, dimensions: 2 });
+ await cache.set('expire', new Float32Array([1, 2]));
+ // Wait 5ms for TTL
+ await new Promise(r => setTimeout(r, 5));
+ const result = await cache.get('expire');
+ assert.equal(result, null);
+ await cache.close();
+ });
+
+ it('binary persistence v2 with createdAt', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('v2.rvec'), dimensions: 2 });
+ await cache.set('persist', new Float32Array([1, 2]));
+ await cache.close();
+
+ // Verify file exists and starts with RVEC magic
+ const buf = readFileSync(tmp('v2.rvec'));
+ assert.equal(buf[0], 0x52); // R
+ assert.equal(buf[1], 0x56); // V
+ assert.equal(buf[2], 0x45); // E
+ assert.equal(buf[3], 0x43); // C
+ // Version should be 2 (uint32 LE at offset 4)
+ assert.equal(buf.readUInt32LE(4), 2);
+
+ // Re-open and verify
+ const cache2 = new RvfEmbeddingCache({ cachePath: tmp('v2.rvec'), dimensions: 2 });
+ const got = await cache2.get('persist');
+ assert.ok(got);
+ assert.equal(got.length, 2);
+ await cache2.close();
+ });
+
+ it('backward compat: reads v1 format files', async () => {
+ // Manually create a v1 format file (no version header)
+ const MAGIC = new Uint8Array([0x52, 0x56, 0x45, 0x43]);
+ const dims = 2;
+ const embedding = new Float32Array([3.14, 2.71]);
+ // v1 entry: hash(4) + dims(4) + data(dims*4) + accessedAt(8) + accessCount(8)
+ const entrySize = 4 + 4 + dims * 4 + 8 + 8;
+ const buf = Buffer.alloc(MAGIC.length + entrySize);
+ buf.set(MAGIC, 0);
+ let off = MAGIC.length;
+ buf.writeUInt32LE(12345, off); off += 4; // hash
+ buf.writeUInt32LE(dims, off); off += 4;
+ for (let i = 0; i < dims; i++) { buf.writeFloatLE(embedding[i], off); off += 4; }
+ buf.writeDoubleLE(Date.now(), off); off += 8; // accessedAt
+ buf.writeDoubleLE(5, off); // accessCount
+
+ writeFileSync(tmp('v1.rvec'), buf);
+
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('v1.rvec'), dimensions: 2 });
+ // The v1 file should load without error (entries are keyed by hash, not text)
+ const size = await cache.size();
+ assert.equal(size, 1);
+ await cache.close();
+ });
+
+ it('dimension validation', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('dim.rvec'), dimensions: 3 });
+ await assert.rejects(
+ () => cache.set('wrong', new Float32Array([1, 2])),
+ /Dimension mismatch/,
+ );
+ await cache.close();
+ });
+});
+
+// =============================================================================
+// 5. RvfEmbeddingService β€” Hash Embeddings
+// =============================================================================
+describe('5. RvfEmbeddingService β€” Hash Embeddings', () => {
+ it('deterministic output', async () => {
+ const svc = new RvfEmbeddingService({ dimensions: 64 });
+ const r1 = await svc.embed('hello world');
+ const r2 = await svc.embed('hello world');
+ assert.deepEqual(r1.embedding, r2.embedding);
+ await svc.shutdown();
+ });
+
+ it('L2 normalized output', async () => {
+ const svc = new RvfEmbeddingService({ dimensions: 128 });
+ const { embedding } = await svc.embed('test normalization');
+ let norm = 0;
+ for (let i = 0; i < embedding.length; i++) norm += embedding[i] ** 2;
+ assert.ok(Math.abs(Math.sqrt(norm) - 1.0) < 0.01, `Expected unit vector, norm=${Math.sqrt(norm)}`);
+ await svc.shutdown();
+ });
+
+ it('embedBatch', async () => {
+ const svc = new RvfEmbeddingService({ dimensions: 32 });
+ const result = await svc.embedBatch(['a', 'b', 'c']);
+ assert.equal(result.embeddings.length, 3);
+ assert.ok(result.totalLatencyMs >= 0);
+ await svc.shutdown();
+ });
+
+ it('in-memory LRU cache', async () => {
+ const svc = new RvfEmbeddingService({ dimensions: 16, cacheSize: 5 });
+ await svc.embed('cached');
+ const r2 = await svc.embed('cached');
+ assert.equal(r2.cached, true);
+ assert.equal(r2.latencyMs, 0);
+ await svc.shutdown();
+ });
+
+ it('persistent cache integration', async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-svc-'));
+ const svc = new RvfEmbeddingService({
+ dimensions: 16, cachePath: join(tmpDir, 'svc-cache.rvec'),
+ });
+ await svc.embed('persist-me');
+ await svc.shutdown();
+
+ // Re-create with fresh in-memory cache but same persistent path
+ const svc2 = new RvfEmbeddingService({
+ dimensions: 16, cachePath: join(tmpDir, 'svc-cache.rvec'),
+ });
+ const r = await svc2.embed('persist-me');
+ assert.equal(r.cached, true);
+ await svc2.shutdown();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('input validation', async () => {
+ const svc = new RvfEmbeddingService({ dimensions: 16 });
+ await assert.rejects(() => svc.embed(123 as any), /string argument/);
+ await assert.rejects(() => svc.embedBatch('not array' as any), /array of strings/);
+ await svc.shutdown();
+ });
+
+ it('dimension validation in constructor', () => {
+ assert.throws(() => new RvfEmbeddingService({ dimensions: 0 }), /Invalid dimensions/);
+ assert.throws(() => new RvfEmbeddingService({ dimensions: -5 }), /Invalid dimensions/);
+ assert.throws(() => new RvfEmbeddingService({ dimensions: 3.5 }), /Invalid dimensions/);
+ });
+});
+
+// =============================================================================
+// 6. RvfLearningStore β€” SONA Persistence
+// =============================================================================
+describe('6. RvfLearningStore β€” SONA Persistence', () => {
+ let store: RvfLearningStore;
+
+ beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-ls-'));
+ store = new RvfLearningStore({ storePath: tmp('learn.rvls'), autoPersistInterval: 0 });
+ await store.initialize();
+ });
+
+ afterEach(async () => {
+ await store.close();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('patterns CRUD', async () => {
+ await store.savePatterns([
+ { id: 'p1', type: 'query', embedding: [0.1, 0.2], successRate: 0.9, useCount: 5, lastUsed: new Date().toISOString() },
+ ]);
+ assert.equal(await store.getPatternCount(), 1);
+ const patterns = await store.loadPatterns();
+ assert.equal(patterns[0].id, 'p1');
+ });
+
+ it('LoRA CRUD', async () => {
+ await store.saveLoraAdapter({ id: 'l1', config: { rank: 4 }, weights: 'base64...', frozen: false, numParameters: 100 });
+ const adapters = await store.loadLoraAdapters();
+ assert.equal(adapters.length, 1);
+ assert.equal(await store.deleteLoraAdapter('l1'), true);
+ assert.equal((await store.loadLoraAdapters()).length, 0);
+ });
+
+ it('EWC state', async () => {
+ await store.saveEwcState({ tasksLearned: 3, protectionStrength: 0.5, forgettingRate: 0.01, taskWeights: {} });
+ const ewc = await store.loadEwcState();
+ assert.ok(ewc);
+ assert.equal(ewc.tasksLearned, 3);
+ });
+
+ it('trajectories', async () => {
+ await store.appendTrajectory({
+ id: 't1', steps: [{ type: 'step', input: 'in', output: 'out', durationMs: 10, confidence: 0.9 }],
+ outcome: 'success', durationMs: 100, timestamp: new Date().toISOString(),
+ });
+ assert.equal(await store.getTrajectoryCount(), 1);
+ const trajs = await store.getTrajectories(1);
+ assert.equal(trajs[0].id, 't1');
+ });
+
+ it('persistence roundtrip', async () => {
+ await store.savePatterns([
+ { id: 'rp1', type: 'test', embedding: [1, 2, 3], successRate: 1, useCount: 0, lastUsed: new Date().toISOString() },
+ ]);
+ await store.persist();
+ await store.close();
+
+ const store2 = new RvfLearningStore({ storePath: tmp('learn.rvls'), autoPersistInterval: 0 });
+ await store2.initialize();
+ assert.equal(await store2.getPatternCount(), 1);
+ store = store2; // for afterEach cleanup
+ });
+
+ it('getStats', async () => {
+ const stats = await store.getStats();
+ assert.equal(stats.patterns, 0);
+ assert.equal(stats.loraAdapters, 0);
+ assert.equal(stats.trajectories, 0);
+ });
+});
+
+// =============================================================================
+// 7. PersistentSonaCoordinator β€” Pattern Matching + Learning
+// =============================================================================
+describe('7. PersistentSonaCoordinator β€” Learning', () => {
+ let sona: PersistentSonaCoordinator;
+
+ beforeEach(async () => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-sona-'));
+ sona = new PersistentSonaCoordinator({
+ storePath: tmp('sona.rvls'), patternThreshold: 0.5, autoPersistInterval: 0,
+ });
+ await sona.initialize();
+ });
+
+ afterEach(async () => {
+ await sona.shutdown();
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('storePattern + findSimilarPatterns', () => {
+ const emb = Array.from({ length: 64 }, (_, i) => Math.sin(i));
+ const id = sona.storePattern('test', emb);
+ assert.ok(id.startsWith('pat-'));
+
+ const similar = sona.findSimilarPatterns(emb, 5);
+ assert.ok(similar.length > 0);
+ assert.equal(similar[0].id, id);
+ });
+
+ it('recordPatternUsage updates success rate', () => {
+ const emb = Array.from({ length: 64 }, () => Math.random());
+ const id = sona.storePattern('usage', emb);
+
+ sona.recordPatternUsage(id, true);
+ sona.recordPatternUsage(id, false);
+
+ const stats = sona.getStats();
+ assert.ok(stats.patterns > 0);
+ assert.ok(stats.avgSuccessRate < 1.0);
+ });
+
+ it('prunePatterns removes low performers', () => {
+ const emb = Array.from({ length: 64 }, () => Math.random());
+ const id = sona.storePattern('low', emb);
+ // Simulate many failures β€” EMA: alpha=0.1, 20 failures drives rate below 0.15
+ for (let i = 0; i < 20; i++) sona.recordPatternUsage(id, false);
+
+ const pruned = sona.prunePatterns(0.5, 5);
+ assert.ok(pruned >= 1);
+ });
+
+ it('recordTrajectory + runBackgroundLoop', () => {
+ sona.recordTrajectory({
+ id: 'traj-1',
+ steps: [{ type: 'code', input: 'fn foo', output: 'done', durationMs: 50, confidence: 0.95 }],
+ outcome: 'success', durationMs: 100, timestamp: new Date().toISOString(),
+ });
+ const result = sona.runBackgroundLoop();
+ assert.ok(result.trajectoriesProcessed >= 1);
+ });
+
+ it('persistence across restart', async () => {
+ sona.storePattern('persist-test', Array.from({ length: 64 }, (_, i) => i * 0.01));
+ await sona.shutdown();
+
+ const sona2 = new PersistentSonaCoordinator({
+ storePath: tmp('sona.rvls'), patternThreshold: 0.5, autoPersistInterval: 0,
+ });
+ await sona2.initialize();
+ const stats = sona2.getStats();
+ assert.ok(stats.patterns >= 1);
+ sona = sona2; // for afterEach cleanup
+ });
+});
+
+// =============================================================================
+// 8. RvfMigrator β€” Bidirectional Migration
+// =============================================================================
+describe('8. RvfMigrator β€” Migration', () => {
+ beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'rvf-mig-')); });
+ afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+ it('detectFormat: json, rvf, unknown', async () => {
+ writeFileSync(tmp('j.json'), '[{"id":"1"}]');
+ assert.equal(await RvfMigrator.detectFormat(tmp('j.json')), 'json');
+
+ // Create RVF file
+ const b = new RvfBackend({ databasePath: tmp('d.rvf') });
+ await b.initialize();
+ await b.store(makeEntry('x'));
+ await b.shutdown();
+ assert.equal(await RvfMigrator.detectFormat(tmp('d.rvf')), 'rvf');
+
+ assert.equal(await RvfMigrator.detectFormat(tmp('no-exist')), 'unknown');
+ });
+
+ it('fromJsonFile + toJsonFile roundtrip', async () => {
+ const entries = [makeEntry('m1'), makeEntry('m2')];
+ const embEntry = { ...entries[0], embedding: [0.1, 0.2, 0.3] };
+ writeFileSync(tmp('src.json'), JSON.stringify([embEntry, entries[1]]));
+
+ const r1 = await RvfMigrator.fromJsonFile(tmp('src.json'), tmp('out.rvf'));
+ assert.equal(r1.success, true);
+ assert.equal(r1.entriesMigrated, 2);
+
+ const r2 = await RvfMigrator.toJsonFile(tmp('out.rvf'), tmp('export.json'));
+ assert.equal(r2.success, true);
+ assert.equal(r2.entriesMigrated, 2);
+
+ const exported = JSON.parse(readFileSync(tmp('export.json'), 'utf-8'));
+ assert.equal(exported.length, 2);
+ });
+
+ it('autoMigrate: json source', async () => {
+ writeFileSync(tmp('auto.json'), JSON.stringify([makeEntry('a1')]));
+ const result = await RvfMigrator.autoMigrate(tmp('auto.json'), tmp('auto.rvf'));
+ assert.equal(result.success, true);
+ assert.equal(result.sourceFormat, 'json');
+ });
+
+ it('progress callback reports progress', async () => {
+ const items = Array.from({ length: 15 }, (_, i) => makeEntry(`pg${i}`));
+ writeFileSync(tmp('prog.json'), JSON.stringify(items));
+
+ const progress: any[] = [];
+ await RvfMigrator.fromJsonFile(tmp('prog.json'), tmp('prog.rvf'), {
+ batchSize: 5,
+ onProgress: (p) => progress.push({ ...p }),
+ });
+ assert.ok(progress.length >= 3); // 15 items / 5 batch = 3+ calls
+ });
+});
+
+// =============================================================================
+// 9. Security Verification
+// =============================================================================
+describe('9. Security β€” Validation & Atomic Writes', () => {
+ beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'rvf-sec-')); });
+ afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+ it('RvfBackend rejects null bytes in path', () => {
+ assert.throws(() => new RvfBackend({ databasePath: '/tmp/evil\0path.rvf' }), /null bytes/);
+ });
+
+ it('RvfBackend allows :memory: path', () => {
+ const b = new RvfBackend({ databasePath: ':memory:' });
+ assert.ok(b); // no throw
+ });
+
+ it('RvfEmbeddingCache rejects null bytes', () => {
+ assert.throws(
+ () => new RvfEmbeddingCache({ cachePath: '/tmp/bad\0cache.rvec' }),
+ /null bytes/,
+ );
+ });
+
+ it('RvfEventLog rejects null bytes', () => {
+ assert.throws(
+ () => new RvfEventLog({ logPath: '/tmp/bad\0log.rvf' }),
+ /null bytes/,
+ );
+ });
+
+ it('RvfBackend uses atomic writes (no .tmp left behind)', async () => {
+ const b = new RvfBackend({ databasePath: tmp('atomic.rvf'), autoPersistInterval: 0 });
+ await b.initialize();
+ await b.store(makeEntry('at1'));
+ await b.shutdown();
+
+ assert.ok(existsSync(tmp('atomic.rvf')));
+ assert.ok(!existsSync(tmp('atomic.rvf.tmp')), '.tmp file should not remain');
+ });
+
+ it('RvfEmbeddingCache uses atomic writes', async () => {
+ const cache = new RvfEmbeddingCache({ cachePath: tmp('atomic.rvec') });
+ await cache.set('x', new Float32Array([1, 2, 3]));
+ await cache.close();
+
+ assert.ok(existsSync(tmp('atomic.rvec')));
+ assert.ok(!existsSync(tmp('atomic.rvec.tmp')), '.tmp file should not remain');
+ });
+
+ it('RvfEventLog uses atomic writes for initial creation', async () => {
+ const log = new RvfEventLog({ logPath: tmp('atomic-log.rvf') });
+ await log.initialize();
+
+ assert.ok(existsSync(tmp('atomic-log.rvf')));
+ assert.ok(!existsSync(tmp('atomic-log.rvf.tmp')));
+ await log.close();
+ });
+});
+
+// =============================================================================
+// 10. Performance β€” Timer Unref, Safe Iteration
+// =============================================================================
+describe('10. Performance β€” Timers & Iteration', () => {
+ beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'rvf-perf-')); });
+ afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+ it('clearNamespace safely handles large datasets', async () => {
+ const b = new RvfBackend({ databasePath: ':memory:', dimensions: 4 });
+ await b.initialize();
+ const entries = Array.from({ length: 500 }, (_, i) => makeEntry(`e${i}`, 'bulk'));
+ await b.bulkInsert(entries);
+ const cleared = await b.clearNamespace('bulk');
+ assert.equal(cleared, 500);
+ assert.equal(await b.count(), 0);
+ await b.shutdown();
+ });
+
+ it('persistToDisk handles 10K entries without stack overflow', async () => {
+ const b = new RvfBackend({ databasePath: tmp('big.rvf'), dimensions: 4, autoPersistInterval: 0 });
+ await b.initialize();
+ const entries = Array.from({ length: 10000 }, (_, i) => ({
+ ...makeEntry(`lg${i}`),
+ createdAt: Date.now() - Math.random() * 100000,
+ }));
+ await b.bulkInsert(entries);
+ await b.shutdown(); // triggers persistToDisk β€” no stack overflow
+
+ // Verify it persisted
+ const b2 = new RvfBackend({ databasePath: tmp('big.rvf'), dimensions: 4 });
+ await b2.initialize();
+ assert.equal(await b2.count(), 10000);
+ await b2.shutdown();
+ });
+});
+
+// =============================================================================
+// 11. DatabaseProvider β€” Auto-Selection
+// =============================================================================
+describe('11. DatabaseProvider Integration', () => {
+ beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'rvf-db-')); });
+ afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+ it('auto-selects RVF when available', async () => {
+ const { createDatabase, getAvailableProviders } = await import('../v3/@claude-flow/memory/src/database-provider.js');
+ const providers = await getAvailableProviders();
+ assert.equal(providers.rvf, true);
+
+ const db = await createDatabase(tmp('auto.db'), { verbose: false });
+ assert.ok(db);
+ // Path should be converted to .rvf
+ await db.store(makeEntry('dp1'));
+ const entry = await db.get('dp1');
+ assert.ok(entry);
+ await db.shutdown();
+ });
+
+ it('converts .db extension to .rvf', async () => {
+ const { createDatabase } = await import('../v3/@claude-flow/memory/src/database-provider.js');
+ const db = await createDatabase(tmp('convert.db'), { provider: 'rvf' });
+ await db.store(makeEntry('cv1'));
+ await db.shutdown();
+ assert.ok(existsSync(tmp('convert.rvf')));
+ });
+});
+
+// =============================================================================
+// Summary
+// =============================================================================
+describe('CAPABILITY SUMMARY', () => {
+ it('all 11 capability areas verified', () => {
+ // This test exists purely as a marker β€” if we get here, all above passed.
+ assert.ok(true, 'All RVF capabilities confirmed');
+ });
+});
diff --git a/tests/rvf-embeddings.test.ts b/tests/rvf-embeddings.test.ts
new file mode 100644
index 0000000000..32694aa8e1
--- /dev/null
+++ b/tests/rvf-embeddings.test.ts
@@ -0,0 +1,571 @@
+/**
+ * Tests for RvfEmbeddingCache and RvfEmbeddingService
+ *
+ * Covers CRUD, LRU eviction, TTL expiry, binary persistence,
+ * dimension validation, deterministic hashing, L2 normalization,
+ * caching, batch operations, interface conformance, and shutdown.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+import { RvfEmbeddingCache } from '../v3/@claude-flow/embeddings/src/rvf-embedding-cache.js';
+import { RvfEmbeddingService } from '../v3/@claude-flow/embeddings/src/rvf-embedding-service.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let tmpDir: string;
+
+function makeTmpDir(): string {
+ return mkdtempSync(join(tmpdir(), 'rvf-test-'));
+}
+
+function makeEmbedding(dims: number, fill = 0.5): Float32Array {
+ const arr = new Float32Array(dims);
+ arr.fill(fill);
+ return arr;
+}
+
+function l2Norm(v: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < v.length; i++) sum += v[i] * v[i];
+ return Math.sqrt(sum);
+}
+
+// ---------------------------------------------------------------------------
+// RvfEmbeddingCache
+// ---------------------------------------------------------------------------
+
+describe('RvfEmbeddingCache', () => {
+ beforeEach(() => {
+ tmpDir = makeTmpDir();
+ });
+
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ // -- CRUD ----------------------------------------------------------------
+
+ describe('CRUD operations', () => {
+ it('set/get stores and retrieves an embedding', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ dimensions: 4,
+ });
+ const emb = makeEmbedding(4, 0.25);
+ await cache.set('hello', emb);
+
+ const result = await cache.get('hello');
+ assert.ok(result, 'Expected non-null result');
+ assert.equal(result.length, 4);
+ assert.ok(Math.abs(result[0] - 0.25) < 1e-6);
+ await cache.close();
+ });
+
+ it('has returns true for existing keys and false for missing keys', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ dimensions: 4,
+ });
+ await cache.set('exists', makeEmbedding(4));
+
+ assert.equal(await cache.has('exists'), true);
+ assert.equal(await cache.has('missing'), false);
+ await cache.close();
+ });
+
+ it('delete removes an entry and returns correct boolean', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ dimensions: 4,
+ });
+ await cache.set('key1', makeEmbedding(4));
+
+ assert.equal(await cache.delete('key1'), true);
+ assert.equal(await cache.has('key1'), false);
+ assert.equal(await cache.delete('key1'), false);
+ await cache.close();
+ });
+
+ it('clear removes all entries', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ dimensions: 4,
+ });
+ await cache.set('a', makeEmbedding(4));
+ await cache.set('b', makeEmbedding(4));
+ assert.equal(await cache.size(), 2);
+
+ await cache.clear();
+ assert.equal(await cache.size(), 0);
+ assert.equal(await cache.has('a'), false);
+ await cache.close();
+ });
+
+ it('size returns the number of entries', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ dimensions: 4,
+ });
+ assert.equal(await cache.size(), 0);
+ await cache.set('x', makeEmbedding(4));
+ assert.equal(await cache.size(), 1);
+ await cache.set('y', makeEmbedding(4));
+ assert.equal(await cache.size(), 2);
+ await cache.close();
+ });
+ });
+
+ // -- LRU Eviction --------------------------------------------------------
+
+ describe('LRU eviction', () => {
+ it('evicts oldest entries when maxSize is exceeded', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ maxSize: 5,
+ dimensions: 4,
+ });
+
+ // Insert 6 entries to exceed maxSize of 5
+ for (let i = 0; i < 6; i++) {
+ await cache.set(`key-${i}`, makeEmbedding(4, i * 0.1));
+ }
+
+ // After eviction to 90% of 5 = 4, size should be <= 5
+ const sz = await cache.size();
+ assert.ok(sz <= 5, `Expected size <= 5, got ${sz}`);
+ await cache.close();
+ });
+ });
+
+ // -- TTL Expiry ----------------------------------------------------------
+
+ describe('TTL expiry', () => {
+ it('returns null for expired entries', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ ttlMs: 1, // 1ms TTL - will expire almost instantly
+ dimensions: 4,
+ });
+ await cache.set('ephemeral', makeEmbedding(4));
+
+ // Wait for the entry to expire
+ await new Promise((resolve) => setTimeout(resolve, 10));
+
+ const result = await cache.get('ephemeral');
+ assert.equal(result, null, 'Expected expired entry to return null');
+ await cache.close();
+ });
+
+ it('has returns false for expired entries', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'cache.rvec'),
+ ttlMs: 1,
+ dimensions: 4,
+ });
+ await cache.set('temp', makeEmbedding(4));
+ await new Promise((resolve) => setTimeout(resolve, 10));
+
+ assert.equal(await cache.has('temp'), false);
+ await cache.close();
+ });
+ });
+
+ // -- Binary Persistence --------------------------------------------------
+
+ describe('binary persistence', () => {
+ it('data survives close and reinit cycle', async () => {
+ const cachePath = join(tmpDir, 'persist.rvec');
+ const emb = makeEmbedding(4, 0.42);
+
+ // Write
+ const cache1 = new RvfEmbeddingCache({
+ cachePath,
+ dimensions: 4,
+ });
+ await cache1.set('persist-test', emb);
+ await cache1.close();
+
+ // Reopen and read
+ const cache2 = new RvfEmbeddingCache({
+ cachePath,
+ dimensions: 4,
+ });
+ const loaded = await cache2.get('persist-test');
+ assert.ok(loaded, 'Expected persisted entry to be loaded');
+ assert.equal(loaded.length, 4);
+ // Float32 precision: values should be very close
+ assert.ok(Math.abs(loaded[0] - 0.42) < 1e-5);
+ await cache2.close();
+ });
+ });
+
+ // -- Binary Format -------------------------------------------------------
+
+ describe('binary format', () => {
+ it('file starts with RVEC magic bytes (0x52 0x56 0x45 0x43)', async () => {
+ const cachePath = join(tmpDir, 'magic.rvec');
+ const cache = new RvfEmbeddingCache({
+ cachePath,
+ dimensions: 4,
+ });
+ await cache.set('magic-check', makeEmbedding(4));
+ await cache.close();
+
+ assert.ok(existsSync(cachePath), 'Cache file should exist');
+ const buf = readFileSync(cachePath);
+ assert.equal(buf[0], 0x52, 'R');
+ assert.equal(buf[1], 0x56, 'V');
+ assert.equal(buf[2], 0x45, 'E');
+ assert.equal(buf[3], 0x43, 'C');
+ });
+ });
+
+ // -- Dimension Validation ------------------------------------------------
+
+ describe('dimension validation', () => {
+ it('throws error when embedding dimensions do not match configured dimensions', async () => {
+ const cache = new RvfEmbeddingCache({
+ cachePath: join(tmpDir, 'dim.rvec'),
+ dimensions: 4,
+ });
+
+ await assert.rejects(
+ () => cache.set('wrong-dims', makeEmbedding(8)),
+ (err: Error) => {
+ assert.ok(err.message.includes('Dimension mismatch'));
+ assert.ok(err.message.includes('expected 4'));
+ assert.ok(err.message.includes('got 8'));
+ return true;
+ }
+ );
+ await cache.close();
+ });
+ });
+});
+
+// ---------------------------------------------------------------------------
+// RvfEmbeddingService
+// ---------------------------------------------------------------------------
+
+describe('RvfEmbeddingService', () => {
+ beforeEach(() => {
+ tmpDir = makeTmpDir();
+ });
+
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ // -- embed() -------------------------------------------------------------
+
+ describe('embed()', () => {
+ it('returns a Float32Array of correct dimensions', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 64 });
+ const result = await svc.embed('test input');
+
+ assert.ok(result.embedding instanceof Float32Array);
+ assert.equal(result.embedding.length, 64);
+ assert.equal(typeof result.latencyMs, 'number');
+ await svc.shutdown();
+ });
+
+ it('uses default 384 dimensions when not specified', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf' });
+ const result = await svc.embed('default dims');
+
+ assert.equal(result.embedding.length, 384);
+ await svc.shutdown();
+ });
+
+ it('is deterministic - same input produces same output', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 32 });
+
+ // Clear cache between calls to force regeneration
+ const r1 = await svc.embed('determinism check');
+ svc.clearCache();
+ const r2 = await svc.embed('determinism check');
+
+ assert.deepEqual(
+ Array.from(r1.embedding as Float32Array),
+ Array.from(r2.embedding as Float32Array),
+ 'Embeddings for the same input must be identical'
+ );
+ await svc.shutdown();
+ });
+
+ it('produces different embeddings for different inputs', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 32 });
+ const r1 = await svc.embed('apple');
+ const r2 = await svc.embed('banana');
+
+ const a = r1.embedding as Float32Array;
+ const b = r2.embedding as Float32Array;
+ let same = true;
+ for (let i = 0; i < a.length; i++) {
+ if (Math.abs(a[i] - b[i]) > 1e-9) { same = false; break; }
+ }
+ assert.equal(same, false, 'Different inputs should yield different embeddings');
+ await svc.shutdown();
+ });
+ });
+
+ // -- L2 Normalization ----------------------------------------------------
+
+ describe('L2 normalization', () => {
+ it('output vectors are unit length (norm approximately 1.0)', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 128 });
+ const result = await svc.embed('normalization test');
+ const norm = l2Norm(result.embedding as Float32Array);
+
+ assert.ok(
+ Math.abs(norm - 1.0) < 1e-5,
+ `Expected norm ~1.0, got ${norm}`
+ );
+ await svc.shutdown();
+ });
+
+ it('multiple different texts all produce unit vectors', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 64 });
+ const texts = ['alpha', 'bravo', 'charlie', 'delta', 'echo'];
+
+ for (const text of texts) {
+ const result = await svc.embed(text);
+ const norm = l2Norm(result.embedding as Float32Array);
+ assert.ok(
+ Math.abs(norm - 1.0) < 1e-5,
+ `Expected unit vector for "${text}", got norm ${norm}`
+ );
+ }
+ await svc.shutdown();
+ });
+ });
+
+ // -- embedBatch() --------------------------------------------------------
+
+ describe('embedBatch()', () => {
+ it('returns the correct number of embeddings', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 32 });
+ const texts = ['one', 'two', 'three', 'four'];
+ const result = await svc.embedBatch(texts);
+
+ assert.equal(result.embeddings.length, 4);
+ assert.equal(typeof result.totalLatencyMs, 'number');
+ assert.equal(typeof result.avgLatencyMs, 'number');
+ await svc.shutdown();
+ });
+
+ it('reports cache hits for previously embedded texts', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 32 });
+
+ // Pre-embed some texts
+ await svc.embed('cached-a');
+ await svc.embed('cached-b');
+
+ // Batch with mix of cached and new
+ const result = await svc.embedBatch(['cached-a', 'cached-b', 'new-c']);
+
+ assert.ok(result.cacheStats, 'Expected cacheStats to be defined');
+ assert.equal(result.cacheStats!.hits, 2);
+ assert.equal(result.cacheStats!.misses, 1);
+ await svc.shutdown();
+ });
+ });
+
+ // -- Caching -------------------------------------------------------------
+
+ describe('caching', () => {
+ it('second call for same text returns cached result', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 32 });
+
+ const r1 = await svc.embed('cache me');
+ assert.ok(!r1.cached, 'First call should not be cached');
+
+ const r2 = await svc.embed('cache me');
+ assert.equal(r2.cached, true, 'Second call should be cached');
+ assert.equal(r2.latencyMs, 0, 'Cached result should report 0 latency');
+ await svc.shutdown();
+ });
+ });
+
+ // -- Persistent Cache Integration ----------------------------------------
+
+ describe('persistent cache integration', () => {
+ it('with cachePath, data persists across service instances', async () => {
+ const cachePath = join(tmpDir, 'svc-persist.rvec');
+
+ // First instance: embed and shutdown
+ const svc1 = new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: 32,
+ cachePath,
+ });
+ const r1 = await svc1.embed('persistent text');
+ await svc1.shutdown();
+
+ // Second instance: should find the persistent entry
+ const svc2 = new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: 32,
+ cachePath,
+ });
+ const r2 = await svc2.embed('persistent text');
+
+ assert.equal(r2.cached, true, 'Should be a cache hit from persistent store');
+ assert.equal(r2.persistentCached, true, 'Should flag persistent cache hit');
+
+ // Verify the embeddings match
+ const a = r1.embedding as Float32Array;
+ const b = r2.embedding as Float32Array;
+ for (let i = 0; i < a.length; i++) {
+ assert.ok(
+ Math.abs(a[i] - b[i]) < 1e-5,
+ `Mismatch at index ${i}: ${a[i]} vs ${b[i]}`
+ );
+ }
+ await svc2.shutdown();
+ });
+ });
+
+ // -- IEmbeddingService Interface -----------------------------------------
+
+ describe('IEmbeddingService interface', () => {
+ it('provider property is "rvf"', () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf' });
+ assert.equal(svc.provider, 'rvf');
+ });
+
+ it('implements all required methods', () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf' });
+ assert.equal(typeof svc.embed, 'function');
+ assert.equal(typeof svc.embedBatch, 'function');
+ assert.equal(typeof svc.clearCache, 'function');
+ assert.equal(typeof svc.getCacheStats, 'function');
+ assert.equal(typeof svc.shutdown, 'function');
+ });
+ });
+
+ // -- getCacheStats() -----------------------------------------------------
+
+ describe('getCacheStats()', () => {
+ it('returns correct hit/miss structure after operations', async () => {
+ const svc = new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: 16,
+ cacheSize: 100,
+ });
+
+ // Initial state
+ const stats0 = svc.getCacheStats();
+ assert.equal(stats0.size, 0);
+ assert.equal(stats0.maxSize, 100);
+ assert.equal(stats0.hitRate, 0);
+
+ // Generate some embeddings
+ await svc.embed('stat-a');
+ await svc.embed('stat-b');
+ await svc.embed('stat-a'); // cache hit
+
+ const stats1 = svc.getCacheStats();
+ assert.equal(stats1.size, 2);
+ assert.ok(stats1.hitRate > 0, 'Hit rate should be > 0 after cache hit');
+ await svc.shutdown();
+ });
+ });
+
+ // -- shutdown() ----------------------------------------------------------
+
+ describe('shutdown()', () => {
+ it('clears in-memory cache', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 16 });
+ await svc.embed('before-shutdown');
+
+ const statsBefore = svc.getCacheStats();
+ assert.equal(statsBefore.size, 1);
+
+ await svc.shutdown();
+
+ const statsAfter = svc.getCacheStats();
+ assert.equal(statsAfter.size, 0);
+ });
+
+ it('closes persistent cache without error', async () => {
+ const svc = new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: 16,
+ cachePath: join(tmpDir, 'shutdown.rvec'),
+ });
+ await svc.embed('shutdown-persist');
+
+ // Should not throw
+ await svc.shutdown();
+ });
+
+ it('removes event listeners on shutdown', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 16 });
+ let called = false;
+ svc.addEventListener(() => { called = true; });
+ await svc.embed('pre-shutdown');
+ assert.equal(called, true, 'Listener should fire before shutdown');
+
+ await svc.shutdown();
+ called = false;
+
+ // After shutdown, listeners should be cleared, but embed still works
+ // (the in-memory cache is cleared, so it regenerates)
+ await svc.embed('post-shutdown');
+ assert.equal(called, false, 'Listener should not fire after shutdown');
+ });
+ });
+
+ // -- Event system --------------------------------------------------------
+
+ describe('event system', () => {
+ it('fires embed_start and embed_complete for new embeddings', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 16 });
+ const events: string[] = [];
+ svc.addEventListener((e) => events.push(e.type));
+
+ await svc.embed('event-test');
+
+ assert.ok(events.includes('embed_start'));
+ assert.ok(events.includes('embed_complete'));
+ await svc.shutdown();
+ });
+
+ it('fires cache_hit for cached embeddings', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 16 });
+ const events: string[] = [];
+ await svc.embed('hit-test'); // first call (miss)
+
+ svc.addEventListener((e) => events.push(e.type));
+ await svc.embed('hit-test'); // second call (hit)
+
+ assert.ok(events.includes('cache_hit'));
+ await svc.shutdown();
+ });
+
+ it('removeEventListener stops delivering events', async () => {
+ const svc = new RvfEmbeddingService({ provider: 'rvf', dimensions: 16 });
+ let count = 0;
+ const listener = () => { count++; };
+
+ svc.addEventListener(listener);
+ await svc.embed('before-remove');
+ const countBefore = count;
+
+ svc.removeEventListener(listener);
+ count = 0;
+ await svc.embed('after-remove');
+ assert.equal(count, 0, 'Listener should not fire after removal');
+ assert.ok(countBefore > 0, 'Listener should have fired before removal');
+ await svc.shutdown();
+ });
+ });
+});
diff --git a/tests/rvf-event-log.test.ts b/tests/rvf-event-log.test.ts
new file mode 100644
index 0000000000..cac3324f13
--- /dev/null
+++ b/tests/rvf-event-log.test.ts
@@ -0,0 +1,643 @@
+/**
+ * Tests for RvfEventLog (ADR-057 Phase 2)
+ *
+ * Covers: initialize, append, getEvents, getAllEvents, snapshots,
+ * stats, persistence, close, and edge cases.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// Use dynamic import β€” tsx handles TS source directly.
+const { RvfEventLog } = await import(
+ '../v3/@claude-flow/shared/src/events/rvf-event-log.ts'
+);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type DomainEvent = {
+ id: string;
+ type: string;
+ aggregateId: string;
+ aggregateType: string;
+ version: number;
+ timestamp: number;
+ source: string;
+ payload: Record<string, unknown>;
+ metadata?: Record<string, unknown>;
+ causationId?: string;
+ correlationId?: string;
+};
+
+type EventSnapshot = {
+ aggregateId: string;
+ aggregateType: string;
+ version: number;
+ state: Record<string, unknown>;
+ timestamp: number;
+};
+
+let tmpCounter = 0;
+
+function makeTmpDir(): string {
+ const dir = join(tmpdir(), `rvf-test-${Date.now()}-${++tmpCounter}`);
+ mkdirSync(dir, { recursive: true });
+ return dir;
+}
+
+function makeEvent(
+ aggregateId: string,
+ type: string,
+ timestampOverride?: number,
+): DomainEvent {
+ return {
+ id: crypto.randomUUID(),
+ type,
+ aggregateId,
+ aggregateType: 'test' as any,
+ timestamp: timestampOverride ?? Date.now(),
+ version: 0,
+ source: 'swarm',
+ payload: {},
+ metadata: { correlationId: crypto.randomUUID(), causationId: '' },
+ };
+}
+
+function makeSnapshot(
+ aggregateId: string,
+ version: number,
+ state: Record<string, unknown> = {},
+): EventSnapshot {
+ return {
+ aggregateId,
+ aggregateType: 'test' as any,
+ version,
+ state,
+ timestamp: Date.now(),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Test state
+// ---------------------------------------------------------------------------
+
+let dir: string;
+let logPath: string;
+
+beforeEach(() => {
+ dir = makeTmpDir();
+ logPath = join(dir, 'events.rvf');
+});
+
+afterEach(() => {
+ if (existsSync(dir)) {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+// ===========================================================================
+// 1. Initialize
+// ===========================================================================
+
+describe('RvfEventLog#initialize', () => {
+ it('creates event file with magic header', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ assert.ok(existsSync(logPath));
+ const buf = readFileSync(logPath);
+ assert.equal(buf.subarray(0, 4).toString(), 'RVFL');
+
+ await log.close();
+ });
+
+ it('creates snapshot file alongside event file', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const snapPath = logPath.replace(/\.rvf$/, '.snap.rvf');
+ assert.ok(existsSync(snapPath));
+ const buf = readFileSync(snapPath);
+ assert.equal(buf.subarray(0, 4).toString(), 'RVFL');
+
+ await log.close();
+ });
+
+ it('rebuilds indexes on re-open', async () => {
+ const log1 = new RvfEventLog({ logPath });
+ await log1.initialize();
+ await log1.append(makeEvent('agg-1', 'created'));
+ await log1.append(makeEvent('agg-1', 'updated'));
+ await log1.close();
+
+ const log2 = new RvfEventLog({ logPath });
+ await log2.initialize();
+
+ const events = await log2.getEvents('agg-1');
+ assert.equal(events.length, 2);
+ assert.equal(events[0].version, 1);
+ assert.equal(events[1].version, 2);
+
+ await log2.close();
+ });
+
+ it('emits initialized event', async () => {
+ const log = new RvfEventLog({ logPath });
+ let emitted = false;
+ log.on('initialized', () => { emitted = true; });
+ await log.initialize();
+
+ assert.ok(emitted);
+ await log.close();
+ });
+
+ it('is idempotent when called twice', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.initialize();
+
+ assert.ok(existsSync(logPath));
+ await log.close();
+ });
+});
+
+// ===========================================================================
+// 2. Append
+// ===========================================================================
+
+describe('RvfEventLog#append', () => {
+ it('assigns incrementing versions per aggregate', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const e1 = makeEvent('agg-A', 'step');
+ const e2 = makeEvent('agg-A', 'step');
+ const e3 = makeEvent('agg-B', 'step');
+
+ await log.append(e1);
+ await log.append(e2);
+ await log.append(e3);
+
+ assert.equal(e1.version, 1);
+ assert.equal(e2.version, 2);
+ assert.equal(e3.version, 1); // separate aggregate
+
+ await log.close();
+ });
+
+ it('persists to disk immediately', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.append(makeEvent('agg-1', 'op'));
+
+ // File should be larger than just the 4-byte magic header.
+ const size = readFileSync(logPath).length;
+ assert.ok(size > 4);
+
+ await log.close();
+ });
+
+ it('emits event:appended', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const captured: any[] = [];
+ log.on('event:appended', (e: any) => captured.push(e));
+
+ const ev = makeEvent('agg-1', 'op');
+ await log.append(ev);
+
+ assert.equal(captured.length, 1);
+ assert.equal(captured[0].id, ev.id);
+
+ await log.close();
+ });
+
+ it('throws when not initialized', async () => {
+ const log = new RvfEventLog({ logPath });
+ await assert.rejects(
+ () => log.append(makeEvent('x', 'y')),
+ /not initialized/i,
+ );
+ });
+});
+
+// ===========================================================================
+// 3. GetEvents
+// ===========================================================================
+
+describe('RvfEventLog#getEvents', () => {
+ it('filters by aggregateId', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ await log.append(makeEvent('agg-A', 'x'));
+ await log.append(makeEvent('agg-B', 'x'));
+ await log.append(makeEvent('agg-A', 'y'));
+
+ const result = await log.getEvents('agg-A');
+ assert.equal(result.length, 2);
+ assert.ok(result.every((e: any) => e.aggregateId === 'agg-A'));
+
+ await log.close();
+ });
+
+ it('filters by fromVersion', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ await log.append(makeEvent('agg-A', 'a'));
+ await log.append(makeEvent('agg-A', 'b'));
+ await log.append(makeEvent('agg-A', 'c'));
+
+ const result = await log.getEvents('agg-A', 2);
+ assert.equal(result.length, 2);
+ assert.equal(result[0].version, 2);
+ assert.equal(result[1].version, 3);
+
+ await log.close();
+ });
+
+ it('returns empty array for unknown aggregate', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.append(makeEvent('agg-A', 'x'));
+
+ const result = await log.getEvents('nonexistent');
+ assert.deepEqual(result, []);
+
+ await log.close();
+ });
+});
+
+// ===========================================================================
+// 4. GetAllEvents
+// ===========================================================================
+
+describe('RvfEventLog#getAllEvents', () => {
+ it('returns all events sorted by timestamp when no filter', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const base = Date.now();
+ await log.append(makeEvent('a', 'x', base + 20));
+ await log.append(makeEvent('b', 'y', base + 10));
+ await log.append(makeEvent('c', 'z', base + 30));
+
+ const result = await log.getAllEvents();
+ assert.equal(result.length, 3);
+ assert.ok(result[0].timestamp <= result[1].timestamp);
+ assert.ok(result[1].timestamp <= result[2].timestamp);
+
+ await log.close();
+ });
+
+ it('filters by eventTypes', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ await log.append(makeEvent('a', 'created'));
+ await log.append(makeEvent('a', 'updated'));
+ await log.append(makeEvent('a', 'deleted'));
+
+ const result = await log.getAllEvents({ eventTypes: ['created', 'deleted'] });
+ assert.equal(result.length, 2);
+ const types = result.map((e: any) => e.type).sort();
+ assert.deepEqual(types, ['created', 'deleted']);
+
+ await log.close();
+ });
+
+ it('filters by timestamps (after/before)', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const base = 1000000;
+ await log.append(makeEvent('a', 'x', base + 100));
+ await log.append(makeEvent('a', 'y', base + 200));
+ await log.append(makeEvent('a', 'z', base + 300));
+
+ const result = await log.getAllEvents({
+ afterTimestamp: base + 100,
+ beforeTimestamp: base + 300,
+ });
+ assert.equal(result.length, 1);
+ assert.equal(result[0].timestamp, base + 200);
+
+ await log.close();
+ });
+
+ it('supports pagination (offset + limit)', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const base = Date.now();
+ for (let i = 0; i < 10; i++) {
+ await log.append(makeEvent('a', 'step', base + i));
+ }
+
+ const page = await log.getAllEvents({ offset: 3, limit: 4 });
+ assert.equal(page.length, 4);
+
+ await log.close();
+ });
+});
+
+// ===========================================================================
+// 5. Snapshots
+// ===========================================================================
+
+describe('RvfEventLog#snapshots', () => {
+ it('saveSnapshot persists and getSnapshot retrieves', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const snap = makeSnapshot('agg-1', 5, { counter: 42 });
+ await log.saveSnapshot(snap);
+
+ const retrieved = await log.getSnapshot('agg-1');
+ assert.ok(retrieved);
+ assert.equal(retrieved!.aggregateId, 'agg-1');
+ assert.equal(retrieved!.version, 5);
+ assert.deepEqual(retrieved!.state, { counter: 42 });
+
+ await log.close();
+ });
+
+ it('returns null for missing snapshot', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const result = await log.getSnapshot('nonexistent');
+ assert.equal(result, null);
+
+ await log.close();
+ });
+
+ it('multiple snapshots: latest wins', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ await log.saveSnapshot(makeSnapshot('agg-1', 3, { v: 'old' }));
+ await log.saveSnapshot(makeSnapshot('agg-1', 7, { v: 'new' }));
+
+ const snap = await log.getSnapshot('agg-1');
+ assert.equal(snap!.version, 7);
+ assert.deepEqual(snap!.state, { v: 'new' });
+
+ await log.close();
+ });
+
+ it('snapshots survive close and re-initialize', async () => {
+ const log1 = new RvfEventLog({ logPath });
+ await log1.initialize();
+ await log1.saveSnapshot(makeSnapshot('agg-1', 10, { val: 99 }));
+ await log1.close();
+
+ const log2 = new RvfEventLog({ logPath });
+ await log2.initialize();
+ const snap = await log2.getSnapshot('agg-1');
+ assert.ok(snap);
+ assert.equal(snap!.version, 10);
+ assert.deepEqual(snap!.state, { val: 99 });
+
+ await log2.close();
+ });
+});
+
+// ===========================================================================
+// 6. Stats
+// ===========================================================================
+
+describe('RvfEventLog#getStats', () => {
+ it('returns correct statistics', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const base = 1000000;
+ await log.append(makeEvent('agg-1', 'created', base + 10));
+ await log.append(makeEvent('agg-1', 'updated', base + 20));
+ await log.append(makeEvent('agg-2', 'created', base + 30));
+ await log.saveSnapshot(makeSnapshot('agg-1', 2));
+
+ const stats = await log.getStats();
+ assert.equal(stats.totalEvents, 3);
+ assert.equal(stats.eventsByType['created'], 2);
+ assert.equal(stats.eventsByType['updated'], 1);
+ assert.equal(stats.eventsByAggregate['agg-1'], 2);
+ assert.equal(stats.eventsByAggregate['agg-2'], 1);
+ assert.equal(stats.oldestEvent, base + 10);
+ assert.equal(stats.newestEvent, base + 30);
+ assert.equal(stats.snapshotCount, 1);
+
+ await log.close();
+ });
+
+ it('returns nulls for empty log', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const stats = await log.getStats();
+ assert.equal(stats.totalEvents, 0);
+ assert.equal(stats.oldestEvent, null);
+ assert.equal(stats.newestEvent, null);
+
+ await log.close();
+ });
+});
+
+// ===========================================================================
+// 7. Persistence
+// ===========================================================================
+
+describe('RvfEventLog persistence', () => {
+ it('data survives close and re-initialize cycle', async () => {
+ const log1 = new RvfEventLog({ logPath });
+ await log1.initialize();
+ await log1.append(makeEvent('agg-1', 'created'));
+ await log1.append(makeEvent('agg-1', 'updated'));
+ await log1.append(makeEvent('agg-2', 'created'));
+ await log1.close();
+
+ const log2 = new RvfEventLog({ logPath });
+ await log2.initialize();
+
+ const all = await log2.getAllEvents();
+ assert.equal(all.length, 3);
+
+ // Versions should continue from where they left off.
+ const e = makeEvent('agg-1', 'deleted');
+ await log2.append(e);
+ assert.equal(e.version, 3);
+
+ await log2.close();
+ });
+
+ it('truncated records are handled gracefully', async () => {
+ const log1 = new RvfEventLog({ logPath });
+ await log1.initialize();
+ await log1.append(makeEvent('agg-1', 'created'));
+ await log1.close();
+
+ // Simulate a truncated write: append a length prefix that claims
+ // more bytes than actually exist.
+ const lengthBuf = Buffer.allocUnsafe(4);
+ lengthBuf.writeUInt32BE(99999, 0);
+ appendFileSync(logPath, Buffer.concat([lengthBuf, Buffer.from('partial')]));
+
+ // Re-open should recover the valid event and skip the truncated one.
+ const log2 = new RvfEventLog({ logPath });
+ await log2.initialize();
+
+ const events = await log2.getEvents('agg-1');
+ assert.equal(events.length, 1);
+ assert.equal(events[0].type, 'created');
+
+ await log2.close();
+ });
+});
+
+// ===========================================================================
+// 8. Close
+// ===========================================================================
+
+describe('RvfEventLog#close', () => {
+ it('clears in-memory state', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.append(makeEvent('agg-1', 'x'));
+ await log.close();
+
+ // After close, operations should fail because initialized is false.
+ await assert.rejects(() => log.getEvents('agg-1'), /not initialized/i);
+ await assert.rejects(() => log.getAllEvents(), /not initialized/i);
+ await assert.rejects(() => log.getStats(), /not initialized/i);
+ });
+
+ it('prevents append after close', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.close();
+
+ await assert.rejects(
+ () => log.append(makeEvent('x', 'y')),
+ /not initialized/i,
+ );
+ });
+
+ it('emits shutdown event', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ let emitted = false;
+ log.on('shutdown', () => { emitted = true; });
+ await log.close();
+
+ assert.ok(emitted);
+ });
+
+ it('is idempotent', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+ await log.close();
+ await log.close(); // should not throw
+ });
+});
+
+// ===========================================================================
+// 9. Edge Cases
+// ===========================================================================
+
+describe('RvfEventLog edge cases', () => {
+ it('empty log returns empty arrays', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ assert.deepEqual(await log.getEvents('anything'), []);
+ assert.deepEqual(await log.getAllEvents(), []);
+
+ await log.close();
+ });
+
+ it('corrupt JSON records are skipped', async () => {
+ // Create a valid file with magic header, then inject bad JSON.
+ writeFileSync(logPath, Buffer.from('RVFL'));
+ const badPayload = Buffer.from('{{{invalid json');
+ const lenBuf = Buffer.allocUnsafe(4);
+ lenBuf.writeUInt32BE(badPayload.length, 0);
+ appendFileSync(logPath, Buffer.concat([lenBuf, badPayload]));
+
+ // Now append a valid record manually.
+ const validEvent = makeEvent('agg-1', 'ok');
+ validEvent.version = 1;
+ const validJson = Buffer.from(JSON.stringify(validEvent), 'utf8');
+ const validLen = Buffer.allocUnsafe(4);
+ validLen.writeUInt32BE(validJson.length, 0);
+ appendFileSync(logPath, Buffer.concat([validLen, validJson]));
+
+ // Also create the snapshot file so initialize does not fail.
+ const snapPath = logPath.replace(/\.rvf$/, '.snap.rvf');
+ writeFileSync(snapPath, Buffer.from('RVFL'));
+
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const events = await log.getEvents('agg-1');
+ assert.equal(events.length, 1);
+ assert.equal(events[0].type, 'ok');
+
+ await log.close();
+ });
+
+ it('handles large number of events', async () => {
+ const log = new RvfEventLog({ logPath });
+ await log.initialize();
+
+ const count = 500;
+ for (let i = 0; i < count; i++) {
+ await log.append(makeEvent('bulk', 'tick', Date.now() + i));
+ }
+
+ const all = await log.getAllEvents();
+ assert.equal(all.length, count);
+
+ const stats = await log.getStats();
+ assert.equal(stats.totalEvents, count);
+
+ await log.close();
+ });
+
+ it('invalid file header throws', async () => {
+ writeFileSync(logPath, Buffer.from('BAAD'));
+ const snapPath = logPath.replace(/\.rvf$/, '.snap.rvf');
+ writeFileSync(snapPath, Buffer.from('RVFL'));
+
+ const log = new RvfEventLog({ logPath });
+ await assert.rejects(() => log.initialize(), /Invalid file header/);
+ });
+
+ it('snapshot:recommended emitted at threshold', async () => {
+ const log = new RvfEventLog({ logPath, snapshotThreshold: 3 });
+ await log.initialize();
+
+ const recommended: any[] = [];
+ log.on('snapshot:recommended', (info: any) => recommended.push(info));
+
+ for (let i = 0; i < 6; i++) {
+ await log.append(makeEvent('agg-1', 'tick'));
+ }
+
+ // Versions 3 and 6 should trigger the recommendation.
+ assert.equal(recommended.length, 2);
+ assert.equal(recommended[0].version, 3);
+ assert.equal(recommended[1].version, 6);
+
+ await log.close();
+ });
+});
diff --git a/tests/rvf-integration.test.ts b/tests/rvf-integration.test.ts
new file mode 100644
index 0000000000..97d7e2d216
--- /dev/null
+++ b/tests/rvf-integration.test.ts
@@ -0,0 +1,405 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Use dynamic imports so the test can run against the compiled JS output.
+// Adjust the import path if your build emits to a different directory.
+const {
+ createDatabase,
+ getAvailableProviders,
+} = await import('../v3/@claude-flow/memory/src/database-provider.js');
+
+type MemoryEntry = import('../v3/@claude-flow/memory/src/types.js').MemoryEntry;
+type IMemoryBackend = import('../v3/@claude-flow/memory/src/types.js').IMemoryBackend;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(
+ id: string,
+ namespace: string,
+ key: string,
+ content: string,
+ embedding?: number[],
+): MemoryEntry {
+ return {
+ id,
+ namespace,
+ key,
+ content,
+ type: 'knowledge' as any,
+ accessLevel: 'shared' as any,
+ tags: [],
+ metadata: {},
+ embedding: embedding ? new Float32Array(embedding) : undefined,
+ createdAt: Date.now(),
+ updatedAt: Date.now(),
+ lastAccessedAt: Date.now(),
+ accessCount: 0,
+ version: 1,
+ ownerId: 'test',
+ references: [],
+ };
+}
+
+let tmpDir: string;
+
+// ---------------------------------------------------------------------------
+// 1. Provider Selection
+// ---------------------------------------------------------------------------
+
+describe('Provider Selection', () => {
+ before(() => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-prov-'));
+ });
+ after(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ it('createDatabase with provider "rvf" creates an RvfBackend', async () => {
+ const db = await createDatabase(join(tmpDir, 'test-rvf.rvf'), {
+ provider: 'rvf',
+ });
+ // RvfBackend exposes healthCheck that reports index component
+ const health = await db.healthCheck();
+ assert.ok(health);
+ assert.equal(health.status, 'healthy');
+ await db.shutdown();
+ });
+
+ it('createDatabase with provider "json" creates a JsonBackend', async () => {
+ const db = await createDatabase(join(tmpDir, 'test-json.json'), {
+ provider: 'json',
+ });
+ const health = await db.healthCheck();
+ assert.ok(health);
+ // JsonBackend always returns 'healthy' and recommends SQLite
+ assert.equal(health.status, 'healthy');
+ assert.ok(
+ health.recommendations.some((r: string) =>
+ r.toLowerCase().includes('sqlite'),
+ ),
+ );
+ await db.shutdown();
+ });
+
+ it('createDatabase with provider "auto" selects RVF', async () => {
+ const db = await createDatabase(join(tmpDir, 'test-auto.db'), {
+ provider: 'auto',
+ });
+ // Because testRvf() always returns true, auto should pick rvf.
+ // Store + get round-trip proves it initialised correctly.
+ const entry = makeEntry('auto-1', 'ns', 'k', 'hello');
+ await db.store(entry);
+ const got = await db.get('auto-1');
+ assert.ok(got);
+ assert.equal(got.content, 'hello');
+ await db.shutdown();
+ });
+
+ it('getAvailableProviders returns rvf: true and json: true', async () => {
+ const providers = await getAvailableProviders();
+ assert.equal(providers.rvf, true);
+ assert.equal(providers.json, true);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// 2. RVF Path Extension
+// ---------------------------------------------------------------------------
+
+describe('RVF Path Extension', () => {
+ let db: IMemoryBackend;
+ let dir: string;
+
+ before(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'rvf-ext-'));
+ db = await createDatabase(join(dir, 'foo.db'), { provider: 'rvf' });
+ });
+ after(async () => {
+ await db.shutdown();
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('input path foo.db is converted to foo.rvf for rvf provider', async () => {
+ // Store an entry and shutdown to force persist, then check file exists.
+ const entry = makeEntry('ext-1', 'ns', 'k', 'data');
+ await db.store(entry);
+ await db.shutdown();
+
+ const { existsSync } = await import('node:fs');
+ // The .db extension should have been replaced with .rvf
+ assert.ok(
+ existsSync(join(dir, 'foo.rvf')),
+ 'Expected foo.rvf to exist on disk',
+ );
+ assert.ok(
+ !existsSync(join(dir, 'foo.db')),
+ 'foo.db should NOT exist (path was rewritten)',
+ );
+
+ // Re-open for later cleanup
+ db = await createDatabase(join(dir, 'foo.db'), { provider: 'rvf' });
+ });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Full IMemoryBackend Contract (RVF via createDatabase)
+// ---------------------------------------------------------------------------
+
+describe('IMemoryBackend Contract (RVF)', () => {
+ let db: IMemoryBackend;
+ let dir: string;
+
+ before(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'rvf-contract-'));
+ db = await createDatabase(join(dir, 'contract.rvf'), { provider: 'rvf' });
+ });
+ after(async () => {
+ await db.shutdown();
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('store + get round-trip', async () => {
+ const entry = makeEntry('c-1', 'ns1', 'key1', 'value1');
+ await db.store(entry);
+ const got = await db.get('c-1');
+ assert.ok(got);
+ assert.equal(got.id, 'c-1');
+ assert.equal(got.content, 'value1');
+ });
+
+ it('store + getByKey round-trip', async () => {
+ const entry = makeEntry('c-2', 'ns1', 'key2', 'value2');
+ await db.store(entry);
+ const got = await db.getByKey('ns1', 'key2');
+ assert.ok(got);
+ assert.equal(got.id, 'c-2');
+ assert.equal(got.content, 'value2');
+ });
+
+ it('update changes version', async () => {
+ const entry = makeEntry('c-3', 'ns1', 'key3', 'original');
+ await db.store(entry);
+ const updated = await db.update('c-3', { content: 'modified' });
+ assert.ok(updated);
+ assert.equal(updated.version, 2);
+ assert.equal(updated.content, 'modified');
+ assert.ok(updated.updatedAt >= entry.updatedAt);
+ });
+
+ it('delete removes entry', async () => {
+ const entry = makeEntry('c-4', 'ns1', 'key4', 'to-delete');
+ await db.store(entry);
+ const deleted = await db.delete('c-4');
+ assert.equal(deleted, true);
+ const got = await db.get('c-4');
+ assert.equal(got, null);
+ });
+
+ it('delete returns false for non-existent id', async () => {
+ const deleted = await db.delete('non-existent');
+ assert.equal(deleted, false);
+ });
+
+ it('bulkInsert + count', async () => {
+ const entries = [
+ makeEntry('b-1', 'bulk', 'bk1', 'bulk1'),
+ makeEntry('b-2', 'bulk', 'bk2', 'bulk2'),
+ makeEntry('b-3', 'bulk', 'bk3', 'bulk3'),
+ ];
+ await db.bulkInsert(entries);
+ const c = await db.count('bulk');
+ assert.equal(c, 3);
+ });
+
+ it('bulkDelete removes entries', async () => {
+ const removed = await db.bulkDelete(['b-1', 'b-2']);
+ assert.equal(removed, 2);
+ const c = await db.count('bulk');
+ assert.equal(c, 1);
+ });
+
+ it('listNamespaces returns unique namespaces', async () => {
+ const namespaces = await db.listNamespaces();
+ assert.ok(namespaces.includes('ns1'));
+ assert.ok(namespaces.includes('bulk'));
+ // Each namespace appears exactly once
+ const unique = new Set(namespaces);
+ assert.equal(unique.size, namespaces.length);
+ });
+
+ it('clearNamespace removes entries for that namespace', async () => {
+ // Add entries to a fresh namespace
+ await db.store(makeEntry('cn-1', 'clearme', 'ck1', 'v1'));
+ await db.store(makeEntry('cn-2', 'clearme', 'ck2', 'v2'));
+ const cleared = await db.clearNamespace('clearme');
+ assert.equal(cleared, 2);
+ const c = await db.count('clearme');
+ assert.equal(c, 0);
+ });
+
+ it('search returns results sorted by score', async () => {
+ const dim = 4;
+ const e1 = makeEntry('s-1', 'search', 'sk1', 'apple', [1, 0, 0, 0]);
+ const e2 = makeEntry('s-2', 'search', 'sk2', 'banana', [0.9, 0.1, 0, 0]);
+ const e3 = makeEntry('s-3', 'search', 'sk3', 'cherry', [0, 0, 1, 0]);
+ await db.bulkInsert([e1, e2, e3]);
+
+ const query = new Float32Array([1, 0, 0, 0]);
+ const results = await db.search(query, { k: 3 });
+
+ assert.ok(results.length >= 2);
+ // Results should be sorted descending by score
+ for (let i = 1; i < results.length; i++) {
+ assert.ok(
+ results[i - 1].score >= results[i].score,
+ `results[${i - 1}].score (${results[i - 1].score}) should be >= results[${i}].score (${results[i].score})`,
+ );
+ }
+ // The closest match to [1,0,0,0] should be s-1 or s-2
+ assert.ok(['s-1', 's-2'].includes(results[0].entry.id));
+ });
+
+ it('healthCheck returns healthy status', async () => {
+ const health = await db.healthCheck();
+ assert.equal(health.status, 'healthy');
+ assert.ok(health.timestamp > 0);
+ assert.ok(health.components.storage.status === 'healthy');
+ });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Data Migration Scenario (JSON -> RVF)
+// ---------------------------------------------------------------------------
+
+describe('Data Migration (JSON -> RVF)', () => {
+ let dir: string;
+
+ before(() => {
+ dir = mkdtempSync(join(tmpdir(), 'rvf-migrate-'));
+ });
+ after(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('entries from JsonBackend can be migrated to RvfBackend', async () => {
+ // Step 1: Create JsonBackend with entries
+ const jsonDb = await createDatabase(join(dir, 'source.json'), {
+ provider: 'json',
+ });
+ const entries = [
+ makeEntry('m-1', 'migrate', 'mk1', 'first'),
+ makeEntry('m-2', 'migrate', 'mk2', 'second'),
+ makeEntry('m-3', 'other', 'mk3', 'third'),
+ ];
+ await jsonDb.bulkInsert(entries);
+
+ // Step 2: Create RvfBackend
+ const rvfDb = await createDatabase(join(dir, 'dest.rvf'), {
+ provider: 'rvf',
+ });
+
+ // Step 3: Copy entries from JSON to RVF
+ for (const entry of entries) {
+ await rvfDb.store(entry);
+ }
+
+ // Step 4: Verify all entries accessible in RVF
+ for (const entry of entries) {
+ const got = await rvfDb.get(entry.id);
+ assert.ok(got, `Entry ${entry.id} should exist in RVF`);
+ assert.equal(got.content, entry.content);
+ assert.equal(got.namespace, entry.namespace);
+ }
+
+ // Verify namespaces preserved
+ const namespaces = await rvfDb.listNamespaces();
+ assert.ok(namespaces.includes('migrate'));
+ assert.ok(namespaces.includes('other'));
+
+ // Verify counts
+ assert.equal(await rvfDb.count('migrate'), 2);
+ assert.equal(await rvfDb.count('other'), 1);
+
+ await jsonDb.shutdown();
+ await rvfDb.shutdown();
+ });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Concurrent Operations
+// ---------------------------------------------------------------------------
+
+describe('Concurrent Operations', () => {
+ let db: IMemoryBackend;
+ let dir: string;
+
+ before(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'rvf-concurrent-'));
+ db = await createDatabase(join(dir, 'concurrent.rvf'), {
+ provider: 'rvf',
+ });
+ });
+ after(async () => {
+ await db.shutdown();
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('multiple stores in parallel do not corrupt state', async () => {
+ const count = 50;
+ const promises: Promise<void>[] = [];
+ for (let i = 0; i < count; i++) {
+ const entry = makeEntry(
+ `par-${i}`,
+ 'parallel',
+ `pk-${i}`,
+ `value-${i}`,
+ );
+ promises.push(db.store(entry));
+ }
+ await Promise.all(promises);
+
+ const total = await db.count('parallel');
+ assert.equal(total, count);
+
+ // Verify each entry is individually accessible
+ for (let i = 0; i < count; i++) {
+ const got = await db.get(`par-${i}`);
+ assert.ok(got, `Entry par-${i} should exist`);
+ assert.equal(got.content, `value-${i}`);
+ }
+ });
+
+ it('store while search is running works correctly', async () => {
+ // Seed entries with embeddings for search
+ const dim = 4;
+ for (let i = 0; i < 10; i++) {
+ const vec = [0, 0, 0, 0];
+ vec[i % dim] = 1;
+ await db.store(
+ makeEntry(`ss-${i}`, 'searchstore', `ssk-${i}`, `sv-${i}`, vec),
+ );
+ }
+
+ // Run search and store concurrently
+ const query = new Float32Array([1, 0, 0, 0]);
+ const [searchResults] = await Promise.all([
+ db.search(query, { k: 5 }),
+ db.store(
+ makeEntry('ss-new', 'searchstore', 'ssk-new', 'new-val', [1, 0, 0, 0]),
+ ),
+ ]);
+
+ assert.ok(Array.isArray(searchResults));
+ assert.ok(searchResults.length > 0);
+
+ // The newly stored entry should be accessible afterwards
+ const newEntry = await db.get('ss-new');
+ assert.ok(newEntry);
+ assert.equal(newEntry.content, 'new-val');
+ });
+});
diff --git a/tests/rvf-learning-store.test.ts b/tests/rvf-learning-store.test.ts
new file mode 100644
index 0000000000..bd1ec007b8
--- /dev/null
+++ b/tests/rvf-learning-store.test.ts
@@ -0,0 +1,443 @@
+/**
+ * Tests for RvfLearningStore
+ *
+ * Covers initialization, pattern/LoRA/EWC/trajectory CRUD, persistence
+ * with RVLS magic header, stats, error handling, and edge cases.
+ *
+ * Run: npx tsx --test tests/rvf-learning-store.test.ts
+ */
+
+import { describe, it, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+ RvfLearningStore,
+ type PatternRecord,
+ type LoraRecord,
+ type EwcRecord,
+ type TrajectoryRecord,
+} from '../v3/@claude-flow/memory/src/rvf-learning-store.js';
+
+// ===== Fixtures =====
+
+function tmpDir(): string {
+ return fs.mkdtempSync(path.join(os.tmpdir(), 'rvf-test-'));
+}
+
+function makePattern(overrides: Partial<PatternRecord> = {}): PatternRecord {
+ return {
+ id: 'p1',
+ type: 'query_response',
+ embedding: [0.1, 0.2, 0.3],
+ successRate: 0.95,
+ useCount: 10,
+ lastUsed: new Date().toISOString(),
+ ...overrides,
+ };
+}
+
+function makeLora(overrides: Partial<LoraRecord> = {}): LoraRecord {
+ return {
+ id: 'lora-1',
+ config: { rank: 8 },
+ weights: 'base64weights==',
+ frozen: false,
+ numParameters: 1024,
+ ...overrides,
+ };
+}
+
+function makeEwc(overrides: Partial<EwcRecord> = {}): EwcRecord {
+ return {
+ tasksLearned: 5,
+ protectionStrength: 0.8,
+ forgettingRate: 0.02,
+ taskWeights: { task1: [0.1, 0.2], task2: [0.3, 0.4] },
+ ...overrides,
+ };
+}
+
+function makeTrajectory(overrides: Partial<TrajectoryRecord> = {}): TrajectoryRecord {
+ return {
+ id: 'traj-1',
+ steps: [
+ { type: 'query', input: 'hello', output: 'world', durationMs: 50, confidence: 0.9 },
+ ],
+ outcome: 'success',
+ durationMs: 100,
+ timestamp: new Date().toISOString(),
+ ...overrides,
+ };
+}
+
+// ===== Tests =====
+
+describe('RvfLearningStore', () => {
+ let dir: string;
+ let storePath: string;
+ let store: RvfLearningStore;
+
+ beforeEach(() => {
+ dir = tmpDir();
+ storePath = path.join(dir, 'test.rvls');
+ store = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ });
+
+ afterEach(async () => {
+ try { await store.close(); } catch { /* already closed or not initialized */ }
+ fs.rmSync(dir, { recursive: true, force: true });
+ });
+
+ // ===== 1. Initialize =====
+
+ describe('initialize', () => {
+ it('creates parent directory if it does not exist', async () => {
+ const nested = path.join(dir, 'deep', 'nested', 'store.rvls');
+ const s = new RvfLearningStore({ storePath: nested, autoPersistInterval: 0 });
+ await s.initialize();
+ assert.ok(fs.existsSync(path.dirname(nested)));
+ await s.close();
+ });
+
+ it('loads existing data on init', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern()]);
+ await store.persist();
+ await store.close();
+
+ const store2 = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ await store2.initialize();
+ const patterns = await store2.loadPatterns();
+ assert.equal(patterns.length, 1);
+ assert.equal(patterns[0].id, 'p1');
+ await store2.close();
+ });
+
+ it('is idempotent when called twice', async () => {
+ await store.initialize();
+ await store.initialize(); // should not throw
+ const count = await store.getPatternCount();
+ assert.equal(count, 0);
+ });
+ });
+
+ // ===== 2. Patterns =====
+
+ describe('patterns', () => {
+ before(async () => {});
+
+ it('savePatterns stores and loadPatterns retrieves', async () => {
+ await store.initialize();
+ const saved = await store.savePatterns([makePattern(), makePattern({ id: 'p2' })]);
+ assert.equal(saved, 2);
+ const loaded = await store.loadPatterns();
+ assert.equal(loaded.length, 2);
+ const ids = loaded.map((p) => p.id).sort();
+ assert.deepEqual(ids, ['p1', 'p2']);
+ });
+
+ it('getPatternCount returns correct count', async () => {
+ await store.initialize();
+ assert.equal(await store.getPatternCount(), 0);
+ await store.savePatterns([makePattern()]);
+ assert.equal(await store.getPatternCount(), 1);
+ await store.savePatterns([makePattern({ id: 'p2' }), makePattern({ id: 'p3' })]);
+ assert.equal(await store.getPatternCount(), 3);
+ });
+
+ it('updates existing pattern when ID matches', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern({ successRate: 0.5 })]);
+ await store.savePatterns([makePattern({ successRate: 0.99 })]);
+ assert.equal(await store.getPatternCount(), 1);
+ const loaded = await store.loadPatterns();
+ assert.equal(loaded[0].successRate, 0.99);
+ });
+ });
+
+ // ===== 3. LoRA =====
+
+ describe('lora', () => {
+ it('saveLoraAdapter stores and loadLoraAdapters retrieves', async () => {
+ await store.initialize();
+ await store.saveLoraAdapter(makeLora());
+ const adapters = await store.loadLoraAdapters();
+ assert.equal(adapters.length, 1);
+ assert.equal(adapters[0].id, 'lora-1');
+ assert.equal(adapters[0].numParameters, 1024);
+ });
+
+ it('deleteLoraAdapter removes adapter and returns true', async () => {
+ await store.initialize();
+ await store.saveLoraAdapter(makeLora());
+ const deleted = await store.deleteLoraAdapter('lora-1');
+ assert.equal(deleted, true);
+ const adapters = await store.loadLoraAdapters();
+ assert.equal(adapters.length, 0);
+ });
+
+ it('deleteLoraAdapter returns false for nonexistent ID', async () => {
+ await store.initialize();
+ const deleted = await store.deleteLoraAdapter('nope');
+ assert.equal(deleted, false);
+ });
+ });
+
+ // ===== 4. EWC =====
+
+ describe('ewc', () => {
+ it('saveEwcState stores and loadEwcState retrieves', async () => {
+ await store.initialize();
+ await store.saveEwcState(makeEwc());
+ const state = await store.loadEwcState();
+ assert.ok(state);
+ assert.equal(state.tasksLearned, 5);
+ assert.equal(state.protectionStrength, 0.8);
+ });
+
+ it('loadEwcState returns null when no state stored', async () => {
+ await store.initialize();
+ const state = await store.loadEwcState();
+ assert.equal(state, null);
+ });
+
+ it('saveEwcState replaces previous state', async () => {
+ await store.initialize();
+ await store.saveEwcState(makeEwc({ tasksLearned: 3 }));
+ await store.saveEwcState(makeEwc({ tasksLearned: 10 }));
+ const state = await store.loadEwcState();
+ assert.ok(state);
+ assert.equal(state.tasksLearned, 10);
+ });
+ });
+
+ // ===== 5. Trajectories =====
+
+ describe('trajectories', () => {
+ it('appendTrajectory adds a record', async () => {
+ await store.initialize();
+ await store.appendTrajectory(makeTrajectory());
+ assert.equal(await store.getTrajectoryCount(), 1);
+ });
+
+ it('getTrajectories returns newest first', async () => {
+ await store.initialize();
+ await store.appendTrajectory(makeTrajectory({ id: 't1', timestamp: '2026-01-01' }));
+ await store.appendTrajectory(makeTrajectory({ id: 't2', timestamp: '2026-01-02' }));
+ await store.appendTrajectory(makeTrajectory({ id: 't3', timestamp: '2026-01-03' }));
+ const trajs = await store.getTrajectories();
+ assert.equal(trajs.length, 3);
+ assert.equal(trajs[0].id, 't3'); // newest (last appended) first
+ assert.equal(trajs[2].id, 't1');
+ });
+
+ it('getTrajectoryCount returns correct count', async () => {
+ await store.initialize();
+ assert.equal(await store.getTrajectoryCount(), 0);
+ await store.appendTrajectory(makeTrajectory({ id: 't1' }));
+ await store.appendTrajectory(makeTrajectory({ id: 't2' }));
+ assert.equal(await store.getTrajectoryCount(), 2);
+ });
+
+ it('limit parameter restricts results', async () => {
+ await store.initialize();
+ for (let i = 0; i < 5; i++) {
+ await store.appendTrajectory(makeTrajectory({ id: `t${i}` }));
+ }
+ const limited = await store.getTrajectories(2);
+ assert.equal(limited.length, 2);
+ assert.equal(limited[0].id, 't4'); // newest first
+ assert.equal(limited[1].id, 't3');
+ });
+ });
+
+ // ===== 6. Persistence =====
+
+ describe('persistence', () => {
+ it('persist() writes file to disk', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern()]);
+ assert.ok(!fs.existsSync(storePath)); // not yet persisted
+ await store.persist();
+ assert.ok(fs.existsSync(storePath));
+ });
+
+ it('data survives close and reinitialize', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern(), makePattern({ id: 'p2' })]);
+ await store.saveLoraAdapter(makeLora());
+ await store.saveEwcState(makeEwc());
+ await store.appendTrajectory(makeTrajectory());
+ await store.persist();
+ await store.close();
+
+ const store2 = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ await store2.initialize();
+ assert.equal(await store2.getPatternCount(), 2);
+ assert.equal((await store2.loadLoraAdapters()).length, 1);
+ assert.ok(await store2.loadEwcState());
+ assert.equal(await store2.getTrajectoryCount(), 1);
+ await store2.close();
+ });
+
+ it('file starts with RVLS magic header', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern()]);
+ await store.persist();
+ const content = fs.readFileSync(storePath, 'utf-8');
+ assert.ok(content.startsWith('RVLS\n'));
+ });
+
+ it('skips persist when store is not dirty', async () => {
+ await store.initialize();
+ await store.persist(); // nothing changed, should be no-op
+ assert.ok(!fs.existsSync(storePath));
+ });
+
+ it('close() auto-persists dirty state', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern()]);
+ await store.close();
+ assert.ok(fs.existsSync(storePath));
+
+ const store2 = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ await store2.initialize();
+ assert.equal(await store2.getPatternCount(), 1);
+ await store2.close();
+ });
+ });
+
+ // ===== 7. Stats =====
+
+ describe('stats', () => {
+ it('returns correct counts and file size', async () => {
+ await store.initialize();
+ await store.savePatterns([makePattern(), makePattern({ id: 'p2' })]);
+ await store.saveLoraAdapter(makeLora());
+ await store.saveEwcState(makeEwc());
+ await store.appendTrajectory(makeTrajectory());
+ await store.appendTrajectory(makeTrajectory({ id: 't2' }));
+ await store.persist();
+
+ const stats = await store.getStats();
+ assert.equal(stats.patterns, 2);
+ assert.equal(stats.loraAdapters, 1);
+ assert.equal(stats.trajectories, 2);
+ assert.equal(stats.hasEwcState, true);
+ assert.ok(stats.fileSizeBytes > 0);
+ });
+
+ it('fileSizeBytes is 0 when nothing persisted', async () => {
+ await store.initialize();
+ const stats = await store.getStats();
+ assert.equal(stats.fileSizeBytes, 0);
+ assert.equal(stats.hasEwcState, false);
+ });
+ });
+
+ // ===== 8. Error Handling =====
+
+ describe('error handling', () => {
+ it('operations before initialize throw', async () => {
+ const uninit = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ await assert.rejects(() => uninit.savePatterns([makePattern()]), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.loadPatterns(), { message: /not been initialized/ });
+ await assert.rejects(() => uninit.getPatternCount(), { message: /not been initialized/ });
+ await assert.rejects(() => uninit.saveLoraAdapter(makeLora()), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.loadLoraAdapters(), { message: /not been initialized/ });
+ await assert.rejects(() => uninit.deleteLoraAdapter('x'), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.saveEwcState(makeEwc()), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.loadEwcState(), { message: /not been initialized/ });
+ await assert.rejects(() => uninit.appendTrajectory(makeTrajectory()), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.getTrajectories(), { message: /not been initialized/ });
+ await assert.rejects(() => uninit.getTrajectoryCount(), {
+ message: /not been initialized/,
+ });
+ await assert.rejects(() => uninit.getStats(), { message: /not been initialized/ });
+ });
+
+ it('corrupt file is handled gracefully (bad header)', async () => {
+ fs.writeFileSync(storePath, 'NOT_RVLS\n{"type":"pattern","data":{}}\n');
+ await store.initialize(); // should not throw
+ assert.equal(await store.getPatternCount(), 0);
+ });
+
+ it('corrupt file is handled gracefully (bad JSON lines)', async () => {
+ fs.writeFileSync(storePath, 'RVLS\n{invalid json}\n{"type":"pattern","data":' +
+ JSON.stringify(makePattern()) + '}\n');
+ await store.initialize(); // should not throw, skips bad line
+ assert.equal(await store.getPatternCount(), 1);
+ });
+ });
+
+ // ===== 9. Edge Cases =====
+
+ describe('edge cases', () => {
+ it('empty store returns empty arrays and zero counts', async () => {
+ await store.initialize();
+ assert.deepEqual(await store.loadPatterns(), []);
+ assert.deepEqual(await store.loadLoraAdapters(), []);
+ assert.equal(await store.loadEwcState(), null);
+ assert.deepEqual(await store.getTrajectories(), []);
+ assert.equal(await store.getPatternCount(), 0);
+ assert.equal(await store.getTrajectoryCount(), 0);
+ });
+
+ it('large number of entries persists and reloads correctly', async () => {
+ await store.initialize();
+ const patterns: PatternRecord[] = [];
+ for (let i = 0; i < 200; i++) {
+ patterns.push(makePattern({ id: `p${i}`, useCount: i }));
+ }
+ await store.savePatterns(patterns);
+ for (let i = 0; i < 50; i++) {
+ await store.appendTrajectory(makeTrajectory({ id: `t${i}` }));
+ }
+ await store.persist();
+ await store.close();
+
+ const store2 = new RvfLearningStore({ storePath, autoPersistInterval: 0 });
+ await store2.initialize();
+ assert.equal(await store2.getPatternCount(), 200);
+ assert.equal(await store2.getTrajectoryCount(), 50);
+ const last = (await store2.loadPatterns()).find((p) => p.id === 'p199');
+ assert.ok(last);
+ assert.equal(last.useCount, 199);
+ await store2.close();
+ });
+
+ it('savePatterns returns count of items passed', async () => {
+ await store.initialize();
+ assert.equal(await store.savePatterns([]), 0);
+ assert.equal(await store.savePatterns([makePattern()]), 1);
+ });
+
+ it('stored data is a copy, not a reference', async () => {
+ await store.initialize();
+ const p = makePattern();
+ await store.savePatterns([p]);
+ p.successRate = 0.0; // mutate original
+ const loaded = await store.loadPatterns();
+ assert.equal(loaded[0].successRate, 0.95); // should still be original value
+ });
+
+ it('getTrajectories with limit larger than count returns all', async () => {
+ await store.initialize();
+ await store.appendTrajectory(makeTrajectory({ id: 't1' }));
+ const result = await store.getTrajectories(100);
+ assert.equal(result.length, 1);
+ });
+ });
+});
diff --git a/tests/rvf-migration.test.ts b/tests/rvf-migration.test.ts
new file mode 100644
index 0000000000..74fda539e9
--- /dev/null
+++ b/tests/rvf-migration.test.ts
@@ -0,0 +1,241 @@
+/**
+ * RVF Migration Utility Tests
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { RvfMigrator } from '../v3/@claude-flow/memory/src/rvf-migration.js';
+import { RvfBackend } from '../v3/@claude-flow/memory/src/rvf-backend.js';
+
+describe('RvfMigrator', () => {
+ let tmpDir: string;
+
+ beforeEach(() => {
+ tmpDir = mkdtempSync(join(tmpdir(), 'rvf-mig-'));
+ });
+
+ afterEach(() => {
+ rmSync(tmpDir, { recursive: true, force: true });
+ });
+
+ describe('detectFormat', () => {
+ it('detects RVF format by magic bytes', async () => {
+ const p = join(tmpDir, 'test.rvf');
+ // RVF magic: 0x52 0x56 0x46 0x00
+ writeFileSync(p, Buffer.from([0x52, 0x56, 0x46, 0x00, 0x00, 0x00, 0x00, 0x00]));
+ assert.equal(await RvfMigrator.detectFormat(p), 'rvf');
+ });
+
+ it('detects JSON format', async () => {
+ const p = join(tmpDir, 'test.json');
+ writeFileSync(p, '[{"id":"1"}]');
+ assert.equal(await RvfMigrator.detectFormat(p), 'json');
+ });
+
+ it('detects JSON object format', async () => {
+ const p = join(tmpDir, 'test.json');
+ writeFileSync(p, '{"id":"1"}');
+ assert.equal(await RvfMigrator.detectFormat(p), 'json');
+ });
+
+ it('returns unknown for non-existent file', async () => {
+ assert.equal(await RvfMigrator.detectFormat(join(tmpDir, 'nope')), 'unknown');
+ });
+
+ it('returns unknown for unrecognized format', async () => {
+ const p = join(tmpDir, 'garbage.bin');
+ writeFileSync(p, Buffer.from([0xFF, 0xFE, 0xFD, 0xFC]));
+ assert.equal(await RvfMigrator.detectFormat(p), 'unknown');
+ });
+ });
+
+ describe('fromJsonFile', () => {
+ it('migrates a JSON array to RVF', async () => {
+ const jsonPath = join(tmpDir, 'source.json');
+ const rvfPath = join(tmpDir, 'target.rvf');
+
+ const entries = [
+ { id: 'e1', key: 'k1', content: 'hello world', namespace: 'test', type: 'semantic', tags: ['a'], metadata: {} },
+ { id: 'e2', key: 'k2', content: 'second entry', namespace: 'test', type: 'document', tags: ['b'], metadata: {} },
+ ];
+ writeFileSync(jsonPath, JSON.stringify(entries));
+
+ const result = await RvfMigrator.fromJsonFile(jsonPath, rvfPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 2);
+ assert.equal(result.sourceFormat, 'json');
+ assert.equal(result.targetFormat, 'rvf');
+ assert.equal(result.errors.length, 0);
+ assert.ok(result.durationMs >= 0);
+
+ // Verify the RVF file is readable
+ const backend = new RvfBackend({ databasePath: rvfPath });
+ await backend.initialize();
+ const e1 = await backend.get('e1');
+ assert.ok(e1);
+ assert.equal(e1.content, 'hello world');
+ await backend.shutdown();
+ });
+
+ it('migrates single JSON object (not array)', async () => {
+ const jsonPath = join(tmpDir, 'single.json');
+ const rvfPath = join(tmpDir, 'single.rvf');
+
+ writeFileSync(jsonPath, JSON.stringify({ id: 'solo', key: 'k', content: 'one entry', namespace: 'ns' }));
+ const result = await RvfMigrator.fromJsonFile(jsonPath, rvfPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 1);
+ });
+
+ it('reports error on invalid JSON', async () => {
+ const jsonPath = join(tmpDir, 'bad.json');
+ const rvfPath = join(tmpDir, 'bad.rvf');
+ writeFileSync(jsonPath, 'not valid json{{{');
+
+ const result = await RvfMigrator.fromJsonFile(jsonPath, rvfPath);
+ assert.equal(result.success, false);
+ assert.equal(result.entriesMigrated, 0);
+ assert.ok(result.errors.length > 0);
+ });
+
+ it('fills in default fields for sparse entries', async () => {
+ const jsonPath = join(tmpDir, 'sparse.json');
+ const rvfPath = join(tmpDir, 'sparse.rvf');
+
+ writeFileSync(jsonPath, JSON.stringify([{ content: 'minimal' }]));
+ const result = await RvfMigrator.fromJsonFile(jsonPath, rvfPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 1);
+
+ const backend = new RvfBackend({ databasePath: rvfPath });
+ await backend.initialize();
+ const entries = await backend.query({ type: 'hybrid', limit: 100 });
+ assert.equal(entries.length, 1);
+ assert.equal(entries[0].content, 'minimal');
+ assert.equal(entries[0].namespace, 'default');
+ assert.ok(entries[0].id); // auto-generated
+ await backend.shutdown();
+ });
+
+ it('reports progress via callback', async () => {
+ const jsonPath = join(tmpDir, 'progress.json');
+ const rvfPath = join(tmpDir, 'progress.rvf');
+
+ const entries = Array.from({ length: 10 }, (_, i) => ({
+ id: `e${i}`, key: `k${i}`, content: `content ${i}`,
+ }));
+ writeFileSync(jsonPath, JSON.stringify(entries));
+
+ const progressCalls: Array<{ current: number; total: number; phase: string }> = [];
+ await RvfMigrator.fromJsonFile(jsonPath, rvfPath, {
+ batchSize: 3,
+ onProgress: (p) => progressCalls.push({ ...p }),
+ });
+
+ assert.ok(progressCalls.length > 0);
+ assert.equal(progressCalls[progressCalls.length - 1].total, 10);
+ });
+ });
+
+ describe('toJsonFile', () => {
+ it('exports RVF to JSON and back', async () => {
+ const rvfPath = join(tmpDir, 'roundtrip.rvf');
+ const jsonPath = join(tmpDir, 'export.json');
+
+ // Create RVF with entries
+ const backend = new RvfBackend({ databasePath: rvfPath });
+ await backend.initialize();
+ await backend.store({
+ id: 'rt1', key: 'k1', content: 'roundtrip test', namespace: 'ns',
+ type: 'semantic', tags: ['rt'], metadata: {}, accessLevel: 'private',
+ createdAt: Date.now(), updatedAt: Date.now(), version: 1,
+ references: [], accessCount: 0, lastAccessedAt: Date.now(),
+ });
+ await backend.shutdown();
+
+ // Export to JSON
+ const result = await RvfMigrator.toJsonFile(rvfPath, jsonPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 1);
+ assert.equal(result.sourceFormat, 'rvf');
+ assert.equal(result.targetFormat, 'json');
+
+ // Verify JSON file
+ const exported = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+ assert.ok(Array.isArray(exported));
+ assert.equal(exported.length, 1);
+ assert.equal(exported[0].id, 'rt1');
+ assert.equal(exported[0].content, 'roundtrip test');
+ });
+ });
+
+ describe('autoMigrate', () => {
+ it('auto-detects JSON and migrates', async () => {
+ const jsonPath = join(tmpDir, 'auto.json');
+ const rvfPath = join(tmpDir, 'auto.rvf');
+
+ writeFileSync(jsonPath, JSON.stringify([
+ { id: 'am1', key: 'k', content: 'auto migrate test' },
+ ]));
+
+ const result = await RvfMigrator.autoMigrate(jsonPath, rvfPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 1);
+ assert.equal(result.sourceFormat, 'json');
+ });
+
+ it('returns no-op for RVF source', async () => {
+ const rvfPath = join(tmpDir, 'existing.rvf');
+ const targetPath = join(tmpDir, 'target.rvf');
+
+ // Create a valid RVF file with at least one entry so it persists
+ const backend = new RvfBackend({ databasePath: rvfPath });
+ await backend.initialize();
+ await backend.store({
+ id: 'x', key: 'k', content: 'test', type: 'semantic', namespace: 'ns',
+ tags: [], metadata: {}, accessLevel: 'private',
+ createdAt: Date.now(), updatedAt: Date.now(), version: 1,
+ references: [], accessCount: 0, lastAccessedAt: Date.now(),
+ });
+ await backend.shutdown();
+
+ const result = await RvfMigrator.autoMigrate(rvfPath, targetPath);
+ assert.equal(result.success, true);
+ assert.equal(result.entriesMigrated, 0);
+ assert.equal(result.sourceFormat, 'rvf');
+ });
+
+ it('returns error for unknown format', async () => {
+ const result = await RvfMigrator.autoMigrate(join(tmpDir, 'nonexistent'), join(tmpDir, 'out.rvf'));
+ assert.equal(result.success, false);
+ assert.ok(result.errors.length > 0);
+ });
+ });
+
+ describe('embeddings migration', () => {
+ it('preserves embeddings through JSON roundtrip', async () => {
+ const jsonPath = join(tmpDir, 'emb.json');
+ const rvfPath = join(tmpDir, 'emb.rvf');
+ const jsonOutPath = join(tmpDir, 'emb-out.json');
+
+ const embedding = [0.1, 0.2, 0.3, 0.4];
+ writeFileSync(jsonPath, JSON.stringify([
+ { id: 'emb1', key: 'k', content: 'with embedding', embedding },
+ ]));
+
+ await RvfMigrator.fromJsonFile(jsonPath, rvfPath);
+ await RvfMigrator.toJsonFile(rvfPath, jsonOutPath);
+
+ const exported = JSON.parse(readFileSync(jsonOutPath, 'utf-8'));
+ assert.equal(exported.length, 1);
+ assert.ok(Array.isArray(exported[0].embedding));
+ // Check values are close (float32 precision)
+ for (let i = 0; i < embedding.length; i++) {
+ assert.ok(Math.abs(exported[0].embedding[i] - embedding[i]) < 0.001);
+ }
+ });
+ });
+});
diff --git a/v3/@claude-flow/cli/docker/.dockerignore b/v3/@claude-flow/cli/docker/.dockerignore
new file mode 100644
index 0000000000..1d58aee66a
--- /dev/null
+++ b/v3/@claude-flow/cli/docker/.dockerignore
@@ -0,0 +1,66 @@
+# Ruflo Docker β€” Exclude dev files from build context
+# This keeps the build context small and fast
+
+# Dependencies (installed fresh in Docker)
+node_modules
+**/node_modules
+
+# Source maps and TypeScript source
+**/*.map
+**/*.ts
+!**/*.d.ts
+
+# Tests
+tests
+**/__tests__
+**/*.test.*
+**/*.spec.*
+.vitest
+coverage
+
+# Dev configs
+.eslintrc*
+.prettierrc*
+tsconfig*.json
+vitest.config.*
+jest.config.*
+
+# Git
+.git
+.gitignore
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# CI/CD
+.github
+.circleci
+.travis.yml
+
+# Docker (prevent recursive copy)
+docker/Dockerfile*
+docker/docker-compose*
+docker/.dockerignore
+
+# Temp and build artifacts
+*.log
+*.tmp
+.tmp*
+dist
+data
+.claude
+.claude-flow
+
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+credentials*
diff --git a/v3/@claude-flow/cli/docker/Dockerfile b/v3/@claude-flow/cli/docker/Dockerfile
new file mode 100644
index 0000000000..d2f9f9be04
--- /dev/null
+++ b/v3/@claude-flow/cli/docker/Dockerfile
@@ -0,0 +1,128 @@
+# Ruflo v3.5 β€” Optimized Production Image
+# Multi-stage Alpine build with --omit=optional for <100MB image
+#
+# Build:
+# docker build -t ruflo:lite -f v3/@claude-flow/cli/docker/Dockerfile .
+#
+# Run:
+# docker run --rm ruflo:lite ruflo --version
+# docker run --rm ruflo:lite ruflo doctor
+# echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | docker run --rm -i ruflo:lite
+#
+# Size comparison:
+# npx ruflo@latest (cold): ~1.3GB, 914 packages, 35s startup
+# ruflo:lite image: <100MB, ~60 packages, <5s startup
+
+# ── Stage 1: Install ─────────────────────────────────────────────
+FROM node:22-alpine AS build
+
+RUN apk add --no-cache git
+
+WORKDIR /install
+
+# Install ruflo globally with --omit=optional to skip heavy deps.
+# --ignore-scripts skips preinstall cache scanning (no-op in CI)
+RUN npm install -g ruflo@latest \
+ --omit=optional \
+ --ignore-scripts \
+ --no-audit \
+ --no-fund \
+ && npm cache clean --force
+
+# Prune heavy optional transitive deps that npm still resolves.
+# These are all optionalDependencies of @claude-flow/cli β€” the CLI
+# works fine without them (graceful fallbacks built in).
+# agentic-flow: 238MB (ONNX runtimes, OpenTelemetry, Anthropic SDK)
+# @opentelemetry: 135MB (transitive via agentic-flow)
+# onnxruntime-node/web: 158MB (ML inference, not needed for CLI)
+# @anthropic-ai: 72MB (SDK, only needed when calling API directly)
+# @xenova: 45MB (transformers.js, not needed for CLI)
+# agentdb: 37MB (optional memory backend)
+# @ruvector: 28MB (optional neural patterns)
+# ruvector: 9MB (optional intelligence)
+# onnx-proto: 22MB (protobuf for ONNX)
+# tiktoken: 23MB (token counting, optional)
+# @img: 16MB (image processing, not needed)
+# better-sqlite3: 10MB (native, optional β€” sql.js used instead)
+RUN GLOBAL_PREFIX=$(npm config get prefix) \
+ && CLI_NM="${GLOBAL_PREFIX}/lib/node_modules/ruflo/node_modules" \
+ && rm -rf \
+ "${CLI_NM}/agentic-flow" \
+ "${CLI_NM}/@opentelemetry" \
+ "${CLI_NM}/onnxruntime-node" \
+ "${CLI_NM}/onnxruntime-web" \
+ "${CLI_NM}/onnx-proto" \
+ "${CLI_NM}/@anthropic-ai" \
+ "${CLI_NM}/@xenova" \
+ "${CLI_NM}/agentdb" \
+ "${CLI_NM}/@ruvector" \
+ "${CLI_NM}/ruvector" \
+ "${CLI_NM}/tiktoken" \
+ "${CLI_NM}/@img" \
+ "${CLI_NM}/better-sqlite3" \
+ "${CLI_NM}/sharp" \
+ "${CLI_NM}/@google" \
+ && rm -rf \
+ "${CLI_NM}/@claude-flow/embeddings" \
+ "${CLI_NM}/@claude-flow/memory" \
+ "${CLI_NM}/@claude-flow/codex" \
+ "${CLI_NM}/@claude-flow/guidance" \
+ "${CLI_NM}/@claude-flow/aidefence" \
+ "${CLI_NM}/@claude-flow/plugin-gastown-bridge" \
+ && NESTED="${CLI_NM}/@claude-flow/cli/node_modules" \
+ && rm -rf \
+ "${NESTED}/agentic-flow" \
+ "${NESTED}/@ruvector" \
+ "${NESTED}/agentdb" \
+ && rm -rf \
+ "${CLI_NM}/ruvector-onnx-embeddings-wasm" \
+ "${CLI_NM}/ruvector-core-linux-x64-gnu" \
+ "${CLI_NM}/@claude-flow/neural" \
+ "${CLI_NM}/@grpc" \
+ "${CLI_NM}/gun"
+
+# Stage the pruned install for the production image
+RUN GLOBAL_PREFIX=$(npm config get prefix) \
+ && mkdir -p /staged/lib /staged/bin \
+ && cp -a "${GLOBAL_PREFIX}/lib/node_modules" /staged/lib/ \
+ && cp -a "${GLOBAL_PREFIX}/bin/ruflo" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/claude-flow" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/cli" /staged/bin/ 2>/dev/null || true
+
+# ── Stage 2: Production ──────────────────────────────────────────
+FROM node:22-alpine AS production
+
+# dumb-init for proper PID 1 signal handling
+RUN apk add --no-cache dumb-init git bash ca-certificates curl
+
+# Non-root user
+RUN addgroup -g 1001 -S ruflo \
+ && adduser -S -D -H -u 1001 -h /home/ruflo -s /bin/bash -G ruflo ruflo \
+ && mkdir -p /home/ruflo/.claude-flow /workspace \
+ && chown -R ruflo:ruflo /home/ruflo /workspace
+
+# Copy only the global node_modules and bin links from build stage
+COPY --from=build /staged/lib/node_modules /usr/local/lib/node_modules
+COPY --from=build /staged/bin/ /usr/local/bin/
+
+# Ensure bin symlinks point to the right place
+RUN ln -sf /usr/local/lib/node_modules/ruflo/bin/ruflo.js /usr/local/bin/ruflo 2>/dev/null || true \
+ && ln -sf /usr/local/lib/node_modules/@claude-flow/cli/bin/cli.js /usr/local/bin/claude-flow 2>/dev/null || true \
+ && chmod +x /usr/local/bin/ruflo 2>/dev/null || true \
+ && chmod +x /usr/local/bin/claude-flow 2>/dev/null || true
+
+ENV NODE_ENV=production \
+ CLAUDE_FLOW_LOG_LEVEL=info \
+ HOME=/home/ruflo
+
+# Healthcheck via CLI doctor (timeout after 10s)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+ CMD ruflo doctor --quiet || exit 1
+
+USER ruflo
+WORKDIR /workspace
+
+ENTRYPOINT ["/usr/bin/dumb-init", "--"]
+
+# Default: start MCP server on stdio (most common Docker use case)
+CMD ["ruflo", "mcp", "start"]
diff --git a/v3/@claude-flow/cli/docker/Dockerfile.full b/v3/@claude-flow/cli/docker/Dockerfile.full
new file mode 100644
index 0000000000..0e8dc181db
--- /dev/null
+++ b/v3/@claude-flow/cli/docker/Dockerfile.full
@@ -0,0 +1,68 @@
+# Ruflo v3.5 β€” Full Image (includes optional dependencies)
+# Use this when you need agentic-flow, RuVector, ONNX, or embeddings.
+#
+# Build:
+# docker build -t ruflo:full -f v3/@claude-flow/cli/docker/Dockerfile.full .
+#
+# Run:
+# docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY ruflo:full
+
+# ── Stage 1: Install ─────────────────────────────────────────────
+FROM node:22-alpine AS build
+
+# onnxruntime-node needs build tools on Alpine
+RUN apk add --no-cache git python3 make g++
+
+WORKDIR /install
+
+# Full install β€” includes optional deps (agentic-flow, ruvector, etc.)
+RUN npm install -g ruflo@latest \
+ --no-audit \
+ --no-fund \
+ && npm cache clean --force
+
+# Stage the global install for copying
+RUN GLOBAL_PREFIX=$(npm config get prefix) \
+ && mkdir -p /staged/lib /staged/bin \
+ && cp -a "${GLOBAL_PREFIX}/lib/node_modules" /staged/lib/ \
+ && cp -a "${GLOBAL_PREFIX}/bin/ruflo" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/claude-flow" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/cli" /staged/bin/ 2>/dev/null || true
+
+# ── Stage 2: Production ──────────────────────────────────────────
+FROM node:22-alpine AS production
+
+RUN apk add --no-cache dumb-init git bash ca-certificates curl
+
+# Non-root user
+RUN addgroup -g 1001 -S ruflo \
+ && adduser -S -D -H -u 1001 -h /home/ruflo -s /bin/bash -G ruflo ruflo \
+ && mkdir -p /home/ruflo/.claude-flow /workspace /var/log/ruflo \
+ && chown -R ruflo:ruflo /home/ruflo /workspace /var/log/ruflo
+
+# Copy global node_modules and bin links from build stage
+COPY --from=build /staged/lib/node_modules /usr/local/lib/node_modules
+COPY --from=build /staged/bin/ /usr/local/bin/
+
+# Ensure bin symlinks
+RUN ln -sf /usr/local/lib/node_modules/ruflo/bin/ruflo.js /usr/local/bin/ruflo 2>/dev/null || true \
+ && ln -sf /usr/local/lib/node_modules/@claude-flow/cli/bin/cli.js /usr/local/bin/claude-flow 2>/dev/null || true \
+ && chmod +x /usr/local/bin/ruflo 2>/dev/null || true \
+ && chmod +x /usr/local/bin/claude-flow 2>/dev/null || true
+
+ENV NODE_ENV=production \
+ CLAUDE_FLOW_LOG_LEVEL=info \
+ CLAUDE_FLOW_MEMORY_BACKEND=hybrid \
+ HOME=/home/ruflo
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+ CMD ruflo doctor --quiet || exit 1
+
+USER ruflo
+WORKDIR /workspace
+
+EXPOSE 3000
+
+ENTRYPOINT ["/usr/bin/dumb-init", "--"]
+
+CMD ["ruflo", "daemon", "start", "--foreground"]
diff --git a/v3/@claude-flow/cli/docker/Dockerfile.headless b/v3/@claude-flow/cli/docker/Dockerfile.headless
index 977b96e9cc..95e5222288 100644
--- a/v3/@claude-flow/cli/docker/Dockerfile.headless
+++ b/v3/@claude-flow/cli/docker/Dockerfile.headless
@@ -1,80 +1,112 @@
-# Dockerfile for Claude Flow V3 Headless Worker
+# Ruflo v3.5 β€” Headless Worker Image
# ADR-020: Headless Worker Integration Architecture - Phase 3
#
+# Headless workers run CLI daemon in foreground without interactive terminal.
+# Used by docker-compose.workers.yml for scalable worker pools.
+#
# Build:
-# docker build -t ghcr.io/ruvnet/claude-flow-headless:latest -f Dockerfile.headless .
+# docker build -t ruflo:headless -f v3/@claude-flow/cli/docker/Dockerfile.headless .
#
# Run:
-# docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY ghcr.io/ruvnet/claude-flow-headless:latest
-
-# Stage 1: Base with Node.js
-FROM node:20-alpine AS base
-
-# Install system dependencies
-RUN apk add --no-cache \
- git \
- bash \
- curl \
- ca-certificates \
- dumb-init
-
-# Create non-root user for security
-RUN addgroup -g 1001 -S claude && \
- adduser -S -D -H -u 1001 -h /home/claude -s /bin/bash -G claude claude
-
-# Set up directories
-RUN mkdir -p /home/claude/.claude-flow && \
- mkdir -p /workspace && \
- mkdir -p /var/log/claude-flow && \
- chown -R claude:claude /home/claude /workspace /var/log/claude-flow
-
-# Stage 2: Build dependencies
-FROM base AS deps
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-COPY pnpm-lock.yaml* ./
-
-# Install pnpm and dependencies
-RUN npm install -g pnpm && \
- pnpm install --frozen-lockfile --prod
-
-# Stage 3: Production image
-FROM base AS production
-
-WORKDIR /app
-
-# Copy node_modules from deps stage
-COPY --from=deps /app/node_modules ./node_modules
-
-# Install Claude Code CLI globally
-RUN npm install -g @anthropic-ai/claude-code@latest && \
- npm install -g @claude-flow/cli@v3alpha
-
-# Copy application files
-COPY --chown=claude:claude . .
+# docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY ruflo:headless
+
+# ── Stage 1: Install ─────────────────────────────────────────────
+FROM node:22-alpine AS build
+
+RUN apk add --no-cache git
+
+WORKDIR /install
+
+# Install ruflo with --omit=optional to skip heavy transitive deps
+RUN npm install -g ruflo@latest \
+ --omit=optional \
+ --ignore-scripts \
+ --no-audit \
+ --no-fund \
+ && npm cache clean --force
+
+# Prune heavy optional transitive deps (CLI works without them)
+RUN GLOBAL_PREFIX=$(npm config get prefix) \
+ && CLI_NM="${GLOBAL_PREFIX}/lib/node_modules/ruflo/node_modules" \
+ && rm -rf \
+ "${CLI_NM}/agentic-flow" \
+ "${CLI_NM}/@opentelemetry" \
+ "${CLI_NM}/onnxruntime-node" \
+ "${CLI_NM}/onnxruntime-web" \
+ "${CLI_NM}/onnx-proto" \
+ "${CLI_NM}/@anthropic-ai" \
+ "${CLI_NM}/@xenova" \
+ "${CLI_NM}/agentdb" \
+ "${CLI_NM}/@ruvector" \
+ "${CLI_NM}/ruvector" \
+ "${CLI_NM}/tiktoken" \
+ "${CLI_NM}/@img" \
+ "${CLI_NM}/better-sqlite3" \
+ "${CLI_NM}/sharp" \
+ "${CLI_NM}/@google" \
+ && rm -rf \
+ "${CLI_NM}/@claude-flow/embeddings" \
+ "${CLI_NM}/@claude-flow/memory" \
+ "${CLI_NM}/@claude-flow/codex" \
+ "${CLI_NM}/@claude-flow/guidance" \
+ "${CLI_NM}/@claude-flow/aidefence" \
+ "${CLI_NM}/@claude-flow/plugin-gastown-bridge" \
+ && NESTED="${CLI_NM}/@claude-flow/cli/node_modules" \
+ && rm -rf \
+ "${NESTED}/agentic-flow" \
+ "${NESTED}/@ruvector" \
+ "${NESTED}/agentdb" \
+ && rm -rf \
+ "${CLI_NM}/ruvector-onnx-embeddings-wasm" \
+ "${CLI_NM}/ruvector-core-linux-x64-gnu" \
+ "${CLI_NM}/@claude-flow/neural" \
+ "${CLI_NM}/@grpc" \
+ "${CLI_NM}/gun"
+
+# Stage the pruned install for copying
+RUN GLOBAL_PREFIX=$(npm config get prefix) \
+ && mkdir -p /staged/lib /staged/bin \
+ && cp -a "${GLOBAL_PREFIX}/lib/node_modules" /staged/lib/ \
+ && cp -a "${GLOBAL_PREFIX}/bin/ruflo" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/claude-flow" /staged/bin/ 2>/dev/null || true \
+ && cp -a "${GLOBAL_PREFIX}/bin/cli" /staged/bin/ 2>/dev/null || true
+
+# ── Stage 2: Production ──────────────────────────────────────────
+FROM node:22-alpine AS production
+
+RUN apk add --no-cache dumb-init git bash ca-certificates curl
+
+# Non-root user
+RUN addgroup -g 1001 -S ruflo \
+ && adduser -S -D -H -u 1001 -h /home/ruflo -s /bin/bash -G ruflo ruflo \
+ && mkdir -p /home/ruflo/.claude-flow /workspace /var/log/ruflo \
+ && chown -R ruflo:ruflo /home/ruflo /workspace /var/log/ruflo
+
+# Copy global node_modules and bin links from build stage
+COPY --from=build /staged/lib/node_modules /usr/local/lib/node_modules
+COPY --from=build /staged/bin/ /usr/local/bin/
+
+# Ensure bin symlinks
+RUN ln -sf /usr/local/lib/node_modules/ruflo/bin/ruflo.js /usr/local/bin/ruflo 2>/dev/null || true \
+ && ln -sf /usr/local/lib/node_modules/@claude-flow/cli/bin/cli.js /usr/local/bin/claude-flow 2>/dev/null || true \
+ && chmod +x /usr/local/bin/ruflo 2>/dev/null || true \
+ && chmod +x /usr/local/bin/claude-flow 2>/dev/null || true
-# Set environment variables
ENV NODE_ENV=production \
CLAUDE_CODE_HEADLESS=true \
CLAUDE_CODE_SANDBOX_MODE=strict \
CLAUDE_FLOW_LOG_LEVEL=info \
- HOME=/home/claude
+ HOME=/home/ruflo
-# Health check endpoint
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
- CMD curl -f http://localhost:3000/health || exit 1
+ CMD ruflo doctor --quiet || exit 1
-# Switch to non-root user
-USER claude
+USER ruflo
+WORKDIR /workspace
-# Expose health check port
EXPOSE 3000
-# Use dumb-init to handle signals properly
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
-# Default command: start daemon in foreground
-CMD ["npx", "claude-flow@v3alpha", "daemon", "start", "--foreground", "--headless"]
+# Default: start daemon in headless foreground mode
+CMD ["ruflo", "daemon", "start", "--foreground", "--headless"]
diff --git a/v3/@claude-flow/cli/docker/docker-compose.yml b/v3/@claude-flow/cli/docker/docker-compose.yml
new file mode 100644
index 0000000000..86aa693009
--- /dev/null
+++ b/v3/@claude-flow/cli/docker/docker-compose.yml
@@ -0,0 +1,117 @@
+# Ruflo v3.5 β€” Docker Compose Profiles
+#
+# Profiles:
+# lite β€” MCP server only (stdio), minimal footprint
+# full β€” CLI + daemon + all optional deps
+# workers β€” Scalable worker pool (extends docker-compose.workers.yml)
+#
+# Usage:
+# docker compose -f v3/@claude-flow/cli/docker/docker-compose.yml --profile lite up
+# docker compose -f v3/@claude-flow/cli/docker/docker-compose.yml --profile full up -d
+# docker compose -f v3/@claude-flow/cli/docker/docker-compose.yml --profile workers up -d --scale worker=5
+#
+# Environment (required for full/workers):
+# ANTHROPIC_API_KEY β€” Your Anthropic API key
+
+services:
+ # ── lite: MCP server on stdio (~80MB) ──────────────────────────
+ mcp:
+ profiles: ["lite"]
+ build:
+ context: ../../../..
+ dockerfile: v3/@claude-flow/cli/docker/Dockerfile
+ image: ruflo:lite
+ stdin_open: true
+ environment:
+ - NODE_ENV=production
+ - CLAUDE_FLOW_MCP_TRANSPORT=stdio
+ deploy:
+ resources:
+ limits:
+ cpus: "1"
+ memory: 512M
+ reservations:
+ cpus: "0.25"
+ memory: 128M
+ healthcheck:
+ test: ["CMD", "ruflo", "doctor", "--quiet"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 10s
+
+ # ── full: CLI + daemon + optional deps (~800MB) ────────────────
+ ruflo-full:
+ profiles: ["full"]
+ build:
+ context: ../../../..
+ dockerfile: v3/@claude-flow/cli/docker/Dockerfile.full
+ image: ruflo:full
+ environment:
+ - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+ - NODE_ENV=production
+ - CLAUDE_FLOW_LOG_LEVEL=${CLAUDE_FLOW_LOG_LEVEL:-info}
+ - CLAUDE_FLOW_MEMORY_BACKEND=hybrid
+ volumes:
+ - ruflo-state:/home/ruflo/.claude-flow
+ - ruflo-logs:/var/log/ruflo
+ ports:
+ - "${RUFLO_MCP_PORT:-3000}:3000"
+ deploy:
+ resources:
+ limits:
+ cpus: "4"
+ memory: 8G
+ reservations:
+ cpus: "1"
+ memory: 2G
+ command: ["ruflo", "daemon", "start", "--foreground"]
+ healthcheck:
+ test: ["CMD", "ruflo", "doctor", "--quiet"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 30s
+
+ # ── workers: Scalable worker pool ──────────────────────────────
+ worker:
+ profiles: ["workers"]
+ build:
+ context: ../../../..
+ dockerfile: v3/@claude-flow/cli/docker/Dockerfile
+ image: ruflo:lite
+ environment:
+ - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+ - CLAUDE_CODE_HEADLESS=true
+ - CLAUDE_CODE_SANDBOX_MODE=${CLAUDE_FLOW_SANDBOX:-strict}
+ - CLAUDE_FLOW_WORKERS=${CLAUDE_FLOW_WORKERS:-audit,optimize,testgaps}
+ - NODE_ENV=production
+ volumes:
+ - worker-state:/home/ruflo/.claude-flow
+ - worker-logs:/var/log/ruflo
+ deploy:
+ replicas: ${RUFLO_WORKER_REPLICAS:-3}
+ resources:
+ limits:
+ cpus: "2"
+ memory: 4G
+ reservations:
+ cpus: "0.5"
+ memory: 1G
+ restart_policy:
+ condition: on-failure
+ delay: 5s
+ max_attempts: 3
+ command: ["ruflo", "daemon", "start", "--foreground", "--headless"]
+ healthcheck:
+ test: ["CMD", "ruflo", "doctor", "--quiet"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 30s
+
+volumes:
+ ruflo-state:
+ ruflo-logs:
+ worker-state:
+ worker-logs:
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index 9563a73667..448548d3cf 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -7,8 +7,9 @@
import type { Command, CommandContext, CommandResult } from '../types.js';
import { output } from '../output.js';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
import { execSync, exec } from 'child_process';
import { promisify } from 'util';
@@ -240,54 +241,36 @@ async function checkBuildTools(): Promise<HealthCheck> {
async function checkVersionFreshness(): Promise<HealthCheck> {
try {
// Get current CLI version from package.json
+ // Use import.meta.url to reliably locate our own package.json,
+ // regardless of how deep the compiled file sits (e.g. dist/src/commands/).
let currentVersion = '0.0.0';
try {
- // Get directory of current module and walk up to find package.json
- const moduleUrl = new URL(import.meta.url);
- const modulePath = moduleUrl.protocol === 'file:' ? moduleUrl.pathname : import.meta.url;
- const moduleDir = modulePath.substring(0, modulePath.lastIndexOf('/'));
-
- // Look for package.json in multiple locations
- const possiblePaths = [
- join(moduleDir, '..', 'package.json'), // ../package.json from dist/commands
- join(moduleDir, '..', '..', 'package.json'), // ../../package.json from dist/commands
- join(process.cwd(), 'package.json'), // Current working directory
- join(process.cwd(), 'node_modules/@claude-flow/cli/package.json')
- ];
-
- // Also search in npx cache directories (Linux/macOS)
- const homeDir = process.env.HOME || process.env.USERPROFILE || '';
- if (homeDir) {
- // Check common npx cache locations
+ const thisFile = fileURLToPath(import.meta.url);
+ let dir = dirname(thisFile);
+
+ // Walk up from the current file's directory until we find the
+ // package.json that belongs to @claude-flow/cli (or claude-flow/cli).
+ // Walk until dirname(dir) === dir (filesystem root on any platform).
+ for (;;) {
+ const candidate = join(dir, 'package.json');
try {
- const npxCacheDir = join(homeDir, '.npm', '_npx');
- if (existsSync(npxCacheDir)) {
- const cacheEntries = readdirSync(npxCacheDir);
- for (const entry of cacheEntries) {
- const npxPkgPath = join(npxCacheDir, entry, 'node_modules', '@claude-flow', 'cli', 'package.json');
- if (existsSync(npxPkgPath)) {
- possiblePaths.push(npxPkgPath);
- }
- }
- }
- } catch {
- // Ignore errors scanning npx cache
- }
- }
-
- for (const pkgPath of possiblePaths) {
- try {
- if (existsSync(pkgPath)) {
- const packageJson = JSON.parse(readFileSync(pkgPath, 'utf8'));
- // Make sure it's the right package
- if (packageJson.name === '@claude-flow/cli' && packageJson.version) {
- currentVersion = packageJson.version;
+ if (existsSync(candidate)) {
+ const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+ if (
+ pkg.version &&
+ typeof pkg.name === 'string' &&
+ (pkg.name === '@claude-flow/cli' || pkg.name === 'claude-flow' || pkg.name === 'ruflo')
+ ) {
+ currentVersion = pkg.version;
break;
}
}
} catch {
- continue;
+ // Unreadable/invalid JSON -- skip and keep walking up
}
+ const parent = dirname(dir);
+ if (parent === dir) break; // reached root
+ dir = parent;
}
} catch {
// Fall back to a default
@@ -302,7 +285,7 @@ async function checkVersionFreshness(): Promise<HealthCheck> {
// Query npm for latest version (using alpha tag since that's what we publish to)
let latestVersion = currentVersion;
try {
- const npmInfo = await runCommand('npm view @claude-flow/cli@alpha version 2>/dev/null', 5000);
+ const npmInfo = await runCommand('npm view @claude-flow/cli@alpha version', 5000);
latestVersion = npmInfo.trim();
} catch {
// Can't reach npm registry - skip check
diff --git a/v3/@claude-flow/cli/src/init/executor.ts b/v3/@claude-flow/cli/src/init/executor.ts
index 407a156de3..79e56a80b3 100644
--- a/v3/@claude-flow/cli/src/init/executor.ts
+++ b/v3/@claude-flow/cli/src/init/executor.ts
@@ -268,13 +268,9 @@ function mergeSettingsForUpgrade(existing: Record<string, unknown>): Record<stri
// Platform-specific command wrappers
// Windows: Use PowerShell-compatible commands
// Mac/Linux: Use bash-compatible commands with 2>/dev/null
- const teammateIdleCmd = isWindows
- ? 'npx @claude-flow/cli@latest hooks teammate-idle --auto-assign true 2>$null; exit 0'
- : 'npx @claude-flow/cli@latest hooks teammate-idle --auto-assign true 2>/dev/null || true';
-
- const taskCompletedCmd = isWindows
- ? 'if ($env:TASK_ID) { npx @claude-flow/cli@latest hooks task-completed --task-id $env:TASK_ID --train-patterns true 2>$null }; exit 0'
- : '[ -n "$TASK_ID" ] && npx @claude-flow/cli@latest hooks task-completed --task-id "$TASK_ID" --train-patterns true 2>/dev/null || true';
+ // NOTE: teammateIdleCmd and taskCompletedCmd were removed.
+ // TeammateIdle/TaskCompleted are not valid Claude Code hook events and caused warnings.
+ // Agent Teams hook config lives in claudeFlow.agentTeams.hooks instead.
// 1. Merge env vars (preserve existing, add new)
const existingEnv = (existing.env as Record<string, string>) || {};
@@ -336,37 +332,12 @@ function mergeSettingsForUpgrade(existing: Record<string, unknown>): Record<stri
});
}
- // Add TeammateIdle hook if not present
- if (!existingHooks.TeammateIdle) {
- (merged.hooks as Record<string, unknown[]>).TeammateIdle = [
- {
- hooks: [
- {
- type: 'command',
- command: teammateIdleCmd,
- timeout: 5000,
- continueOnError: true,
- },
- ],
- },
- ];
- }
-
- // Add TaskCompleted hook if not present
- if (!existingHooks.TaskCompleted) {
- (merged.hooks as Record<string, unknown[]>).TaskCompleted = [
- {
- hooks: [
- {
- type: 'command',
- command: taskCompletedCmd,
- timeout: 5000,
- continueOnError: true,
- },
- ],
- },
- ];
- }
+ // NOTE: TeammateIdle and TaskCompleted are NOT valid Claude Code hook events.
+ // They cause warnings when present in settings.json hooks.
+ // Remove them if they exist from a previous init.
+ delete (merged.hooks as Record<string, unknown>).TeammateIdle;
+ delete (merged.hooks as Record<string, unknown>).TaskCompleted;
+ // Their configuration lives in claudeFlow.agentTeams.hooks instead.
// 3. Fix statusLine config (remove invalid fields, ensure correct format)
// Claude Code only supports: type, command, padding
@@ -586,8 +557,8 @@ export async function executeUpgrade(targetDir: string, upgradeSettings = false)
'env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS',
'hooks.SessionStart (auto-memory import)',
'hooks.SessionEnd (auto-memory sync)',
- 'hooks.TeammateIdle',
- 'hooks.TaskCompleted',
+ 'hooks.TeammateIdle (removed β€” not a valid Claude Code hook)',
+ 'hooks.TaskCompleted (removed β€” not a valid Claude Code hook)',
'claudeFlow.agentTeams',
'claudeFlow.memory (learningBridge, memoryGraph, agentScopes)',
];
diff --git a/v3/@claude-flow/cli/src/init/settings-generator.ts b/v3/@claude-flow/cli/src/init/settings-generator.ts
index 2d29415dcb..9b7dde46ea 100644
--- a/v3/@claude-flow/cli/src/init/settings-generator.ts
+++ b/v3/@claude-flow/cli/src/init/settings-generator.ts
@@ -324,31 +324,8 @@ function generateHooksConfig(config: HooksConfig): object {
},
];
- // TeammateIdle β€” auto-assign pending tasks to idle teammates
- hooks.TeammateIdle = [
- {
- hooks: [
- {
- type: 'command',
- command: 'node .claude/helpers/hook-handler.cjs post-task',
- timeout: 5000,
- },
- ],
- },
- ];
-
- // TaskCompleted β€” train patterns and record completion
- hooks.TaskCompleted = [
- {
- hooks: [
- {
- type: 'command',
- command: 'node .claude/helpers/hook-handler.cjs post-task',
- timeout: 5000,
- },
- ],
- },
- ];
+ // NOTE: TeammateIdle and TaskCompleted are NOT valid Claude Code hook events.
+ // Their configuration lives in claudeFlow.agentTeams.hooks instead (see generateSettings).
return hooks;
}
diff --git a/v3/@claude-flow/embeddings/src/embedding-service.ts b/v3/@claude-flow/embeddings/src/embedding-service.ts
index 7619a38120..e22f09ed9d 100644
--- a/v3/@claude-flow/embeddings/src/embedding-service.ts
+++ b/v3/@claude-flow/embeddings/src/embedding-service.ts
@@ -20,6 +20,7 @@ import type {
TransformersEmbeddingConfig,
MockEmbeddingConfig,
AgenticFlowEmbeddingConfig,
+ RvfEmbeddingConfig,
EmbeddingResult,
BatchEmbeddingResult,
IEmbeddingService,
@@ -32,6 +33,7 @@ import type {
} from './types.js';
import { normalize } from './normalization.js';
import { PersistentEmbeddingCache } from './persistent-cache.js';
+import { RvfEmbeddingService } from './rvf-embedding-service.js';
// ============================================================================
// LRU Cache Implementation
@@ -874,6 +876,8 @@ export function createEmbeddingService(config: EmbeddingConfig): IEmbeddingServi
return new MockEmbeddingService(config as MockEmbeddingConfig);
case 'agentic-flow':
return new AgenticFlowEmbeddingService(config as AgenticFlowEmbeddingConfig);
+ case 'rvf':
+ return new RvfEmbeddingService(config as RvfEmbeddingConfig);
default:
console.warn(`Unknown provider, using mock`);
return new MockEmbeddingService({ provider: 'mock', dimensions: 384 });
@@ -927,7 +931,18 @@ export async function createEmbeddingServiceAsync(
// Auto provider selection
if (provider === 'auto') {
- // Try agentic-flow first (fastest, ONNX-based)
+ // Try RVF first (52KB, always available, fast hash embeddings)
+ try {
+ const service = new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: rest.dimensions ?? 384,
+ cacheSize: rest.cacheSize,
+ });
+ await service.embed('test');
+ return service;
+ } catch { /* fall through */ }
+
+ // Try agentic-flow (fastest neural, ONNX-based)
let agenticFlowAvailable = await isAgenticFlowAvailable();
// Auto-install if not available and autoInstall is enabled
@@ -997,6 +1012,12 @@ export async function createEmbeddingServiceAsync(
dimensions: rest.dimensions,
cacheSize: rest.cacheSize,
});
+ case 'rvf':
+ return new RvfEmbeddingService({
+ provider: 'rvf',
+ dimensions: rest.dimensions ?? 384,
+ cacheSize: rest.cacheSize,
+ });
case 'mock':
return new MockEmbeddingService({
dimensions: rest.dimensions ?? 384,
diff --git a/v3/@claude-flow/embeddings/src/index.ts b/v3/@claude-flow/embeddings/src/index.ts
index cea6caf010..1f6cabe8d1 100644
--- a/v3/@claude-flow/embeddings/src/index.ts
+++ b/v3/@claude-flow/embeddings/src/index.ts
@@ -37,6 +37,15 @@ export {
export type { AutoEmbeddingConfig } from './embedding-service.js';
+// RVF embedding service (pure-TS hash-based embeddings)
+export { RvfEmbeddingService } from './rvf-embedding-service.js';
+
+// RVF embedding cache (binary file persistence)
+export {
+ RvfEmbeddingCache,
+ type RvfEmbeddingCacheConfig,
+} from './rvf-embedding-cache.js';
+
// Chunking utilities
export {
chunkText,
@@ -106,6 +115,7 @@ export type {
TransformersEmbeddingConfig,
MockEmbeddingConfig,
AgenticFlowEmbeddingConfig,
+ RvfEmbeddingConfig,
EmbeddingResult,
BatchEmbeddingResult,
IEmbeddingService,
diff --git a/v3/@claude-flow/embeddings/src/rvf-embedding-cache.ts b/v3/@claude-flow/embeddings/src/rvf-embedding-cache.ts
new file mode 100644
index 0000000000..67e96fa8f3
--- /dev/null
+++ b/v3/@claude-flow/embeddings/src/rvf-embedding-cache.ts
@@ -0,0 +1,578 @@
+/**
+ * RVF Embedding Cache - Pure TypeScript Binary File Cache
+ *
+ * Replaces the sql.js-based PersistentEmbeddingCache with a lightweight
+ * pure-TS binary file format. No native dependencies required.
+ *
+ * Features:
+ * - Map-based in-memory cache with periodic flush to binary file
+ * - LRU eviction tracked via access timestamps
+ * - TTL support for cache entries
+ * - Deterministic FNV-1a text hashing for keys
+ * - Binary format: RVEC magic + entry records
+ *
+ * Binary entry format:
+ * [4-byte key-hash][4-byte dims][dims*4 bytes float32][8-byte timestamp][8-byte access-count]
+ *
+ * @module @claude-flow/embeddings
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { dirname } from 'path';
+
+/** Validate a file path is safe */
+function validatePath(p: string): void {
+ if (p.includes('\0')) throw new Error('Cache path contains null bytes');
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Configuration for RVF embedding cache
+ */
+export interface RvfEmbeddingCacheConfig {
+ /** Path to the binary cache file */
+ cachePath: string;
+ /** Maximum number of entries (default: 10000) */
+ maxSize?: number;
+ /** TTL in milliseconds (default: 7 days) */
+ ttlMs?: number;
+ /** Embedding dimensions (used for validation) */
+ dimensions?: number;
+}
+
+// ============================================================================
+// Cache Entry
+// ============================================================================
+
+interface CacheEntry {
+ embedding: Float32Array;
+ createdAt: number;
+ accessedAt: number;
+ accessCount: number;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Binary file magic bytes: "RVEC" */
+const MAGIC = new Uint8Array([0x52, 0x56, 0x45, 0x43]); // R V E C
+
+/** Default TTL: 7 days in milliseconds */
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Default max entries */
+const DEFAULT_MAX_SIZE = 10000;
+
+/** Auto-flush interval: 30 seconds */
+const AUTO_FLUSH_INTERVAL_MS = 30000;
+
+/** FNV-1a offset basis (32-bit) */
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+
+/** FNV-1a prime (32-bit) */
+const FNV_PRIME = 0x01000193;
+
+// ============================================================================
+// RVF Embedding Cache
+// ============================================================================
+
+/**
+ * Pure-TS binary file embedding cache with LRU eviction and TTL support.
+ *
+ * Stores embeddings as raw Float32Array bytes keyed by FNV-1a text hashes.
+ * Uses an in-memory Map with periodic flush to a compact binary file.
+ */
+export class RvfEmbeddingCache {
+ private readonly cachePath: string;
+ private readonly maxSize: number;
+ private readonly ttlMs: number;
+ private readonly dimensions: number | undefined;
+
+ private entries: Map<number, CacheEntry> = new Map();
+ private textToHash: Map<string, number> = new Map();
+ private dirty = false;
+ private flushTimer: ReturnType<typeof setInterval> | null = null;
+ private initialized = false;
+
+ constructor(config: RvfEmbeddingCacheConfig) {
+ this.cachePath = config.cachePath;
+ this.maxSize = config.maxSize ?? DEFAULT_MAX_SIZE;
+ this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+ this.dimensions = config.dimensions;
+ validatePath(this.cachePath);
+ }
+
+ // --------------------------------------------------------------------------
+ // Initialization
+ // --------------------------------------------------------------------------
+
+ /**
+ * Lazily initialize the cache: load from disk if file exists, start auto-flush.
+ */
+ private async ensureInitialized(): Promise<void> {
+ if (this.initialized) return;
+
+ // Ensure parent directory exists
+ const dir = dirname(this.cachePath);
+ if (!existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+
+ // Load existing cache file
+ if (existsSync(this.cachePath)) {
+ this.loadFromFile();
+ }
+
+ // Clean expired entries on startup
+ this.cleanExpired();
+
+ // Start auto-flush timer
+ this.startAutoFlush();
+
+ this.initialized = true;
+ }
+
+ // --------------------------------------------------------------------------
+ // Public API (matches PersistentEmbeddingCache)
+ // --------------------------------------------------------------------------
+
+ /**
+ * Get an embedding from the cache by text.
+ * Returns null if not found or expired.
+ */
+ async get(text: string): Promise<Float32Array | null> {
+ await this.ensureInitialized();
+
+ const hash = this.hashText(text);
+ const entry = this.entries.get(hash);
+
+ if (!entry) {
+ return null;
+ }
+
+ // Check TTL
+ const now = Date.now();
+ if (now - entry.createdAt > this.ttlMs) {
+ this.entries.delete(hash);
+ this.textToHash.delete(text);
+ this.dirty = true;
+ return null;
+ }
+
+ // Update LRU tracking
+ entry.accessedAt = now;
+ entry.accessCount++;
+ this.dirty = true;
+
+ return entry.embedding;
+ }
+
+ /**
+ * Store an embedding in the cache.
+ * Triggers LRU eviction if the cache exceeds maxSize.
+ */
+ async set(text: string, embedding: Float32Array): Promise<void> {
+ await this.ensureInitialized();
+
+ // Validate dimensions if configured
+ if (this.dimensions !== undefined && embedding.length !== this.dimensions) {
+ throw new Error(
+ `Dimension mismatch: expected ${this.dimensions}, got ${embedding.length}`
+ );
+ }
+
+ const hash = this.hashText(text);
+ const now = Date.now();
+
+ // Copy the embedding to avoid external mutation
+ const copy = new Float32Array(embedding.length);
+ copy.set(embedding);
+
+ const existing = this.entries.get(hash);
+ if (existing) {
+ existing.embedding = copy;
+ existing.accessedAt = now;
+ existing.accessCount++;
+ } else {
+ this.entries.set(hash, {
+ embedding: copy,
+ createdAt: now,
+ accessedAt: now,
+ accessCount: 1,
+ });
+ this.textToHash.set(text, hash);
+ }
+
+ this.dirty = true;
+
+ // Evict if over capacity
+ this.evictIfNeeded();
+ }
+
+ /**
+ * Check whether the cache contains an embedding for the given text.
+ */
+ async has(text: string): Promise<boolean> {
+ await this.ensureInitialized();
+
+ const hash = this.hashText(text);
+ const entry = this.entries.get(hash);
+
+ if (!entry) return false;
+
+ // Check TTL
+ if (Date.now() - entry.createdAt > this.ttlMs) {
+ this.entries.delete(hash);
+ this.textToHash.delete(text);
+ this.dirty = true;
+ return false;
+ }
+
+ return true;
+ }
+
+ /**
+ * Delete a specific entry from the cache.
+ * Returns true if the entry existed and was deleted.
+ */
+ async delete(text: string): Promise<boolean> {
+ await this.ensureInitialized();
+
+ const hash = this.hashText(text);
+ const existed = this.entries.delete(hash);
+ this.textToHash.delete(text);
+
+ if (existed) {
+ this.dirty = true;
+ }
+
+ return existed;
+ }
+
+ /**
+ * Clear all entries from the cache and persist the empty state.
+ */
+ async clear(): Promise<void> {
+ await this.ensureInitialized();
+
+ this.entries.clear();
+ this.textToHash.clear();
+ this.dirty = true;
+ this.flushToFile();
+ }
+
+ /**
+ * Return the number of entries currently in the cache.
+ */
+ async size(): Promise<number> {
+ await this.ensureInitialized();
+ return this.entries.size;
+ }
+
+ /**
+ * Flush pending changes to disk and stop the auto-flush timer.
+ */
+ async close(): Promise<void> {
+ this.stopAutoFlush();
+
+ if (this.dirty) {
+ this.flushToFile();
+ }
+
+ this.entries.clear();
+ this.textToHash.clear();
+ this.initialized = false;
+ }
+
+ // --------------------------------------------------------------------------
+ // Hashing
+ // --------------------------------------------------------------------------
+
+ /**
+ * FNV-1a 32-bit hash of the input text.
+ * Deterministic: same input always produces the same hash.
+ */
+ private hashText(text: string): number {
+ let hash = FNV_OFFSET_BASIS;
+ for (let i = 0; i < text.length; i++) {
+ hash ^= text.charCodeAt(i);
+ hash = Math.imul(hash, FNV_PRIME) >>> 0;
+ }
+ return hash;
+ }
+
+ // --------------------------------------------------------------------------
+ // LRU Eviction
+ // --------------------------------------------------------------------------
+
+ /**
+ * If the cache exceeds maxSize, evict the least-recently-accessed entries
+ * until we are back at 90% capacity.
+ */
+ private evictIfNeeded(): void {
+ if (this.entries.size <= this.maxSize) return;
+
+ const targetSize = Math.floor(this.maxSize * 0.9);
+ const toEvict = this.entries.size - targetSize;
+
+ // Sort entries by accessedAt ascending (oldest first)
+ const sorted = [...this.entries.entries()].sort(
+ (a, b) => a[1].accessedAt - b[1].accessedAt
+ );
+
+ // Build reverse map for O(1) lookup (hash β†’ text)
+ const hashToText = new Map<number, string>();
+ for (const [text, hash] of this.textToHash) {
+ hashToText.set(hash, text);
+ }
+
+ for (let i = 0; i < toEvict && i < sorted.length; i++) {
+ const [hash] = sorted[i];
+ this.entries.delete(hash);
+ const text = hashToText.get(hash);
+ if (text !== undefined) this.textToHash.delete(text);
+ }
+
+ this.dirty = true;
+ }
+
+ // --------------------------------------------------------------------------
+ // TTL Cleanup
+ // --------------------------------------------------------------------------
+
+ /**
+ * Remove all entries whose createdAt timestamp is older than TTL.
+ */
+ private cleanExpired(): void {
+ const cutoff = Date.now() - this.ttlMs;
+ const toDelete: number[] = [];
+
+ for (const [hash, entry] of this.entries) {
+ if (entry.createdAt < cutoff) {
+ toDelete.push(hash);
+ }
+ }
+
+ // Build reverse map for O(1) lookup
+ const hashToText = new Map<number, string>();
+ for (const [text, h] of this.textToHash) {
+ hashToText.set(h, text);
+ }
+
+ for (const hash of toDelete) {
+ this.entries.delete(hash);
+ const text = hashToText.get(hash);
+ if (text !== undefined) this.textToHash.delete(text);
+ }
+
+ if (toDelete.length > 0) {
+ this.dirty = true;
+ }
+ }
+
+ // --------------------------------------------------------------------------
+ // Auto-Flush Timer
+ // --------------------------------------------------------------------------
+
+ private startAutoFlush(): void {
+ if (this.flushTimer) return;
+
+ this.flushTimer = setInterval(() => {
+ if (this.dirty) {
+ this.flushToFile();
+ }
+ }, AUTO_FLUSH_INTERVAL_MS);
+ if (this.flushTimer.unref) this.flushTimer.unref();
+ }
+
+ private stopAutoFlush(): void {
+ if (this.flushTimer) {
+ clearInterval(this.flushTimer);
+ this.flushTimer = null;
+ }
+ }
+
+ // --------------------------------------------------------------------------
+ // Binary Serialization
+ // --------------------------------------------------------------------------
+
+ /**
+ * Write all entries to the binary cache file.
+ *
+ * Format:
+ * [4-byte magic "RVEC"]
+ * For each entry:
+ * [4-byte key-hash (uint32)]
+ * [4-byte dims (uint32)]
+ * [dims * 4 bytes float32 data]
+ * [8-byte createdAt (float64, used as timestamp)]
+ * [8-byte accessCount (float64)]
+ */
+ private flushToFile(): void {
+ try {
+ // Version 2 format: magic(4) + version(4) + entries...
+ // Entry: hash(4) + dims(4) + embedding(dims*4) + createdAt(8) + accessedAt(8) + accessCount(8)
+ let totalSize = MAGIC.length + 4; // magic + version uint32
+ for (const [, entry] of this.entries) {
+ totalSize += 4 + 4 + entry.embedding.length * 4 + 8 + 8 + 8;
+ }
+
+ const buffer = new ArrayBuffer(totalSize);
+ const view = new DataView(buffer);
+ const bytes = new Uint8Array(buffer);
+ let offset = 0;
+
+ // Write magic
+ bytes.set(MAGIC, 0);
+ offset += MAGIC.length;
+
+ // Write format version
+ view.setUint32(offset, 2, true);
+ offset += 4;
+
+ // Write entries
+ for (const [hash, entry] of this.entries) {
+ // Key hash (uint32, little-endian)
+ view.setUint32(offset, hash, true);
+ offset += 4;
+
+ // Dimensions (uint32, little-endian)
+ view.setUint32(offset, entry.embedding.length, true);
+ offset += 4;
+
+ // Embedding data (float32 array, little-endian)
+ for (let i = 0; i < entry.embedding.length; i++) {
+ view.setFloat32(offset, entry.embedding[i], true);
+ offset += 4;
+ }
+
+ // createdAt as float64 (little-endian) - v2: separate from accessedAt
+ view.setFloat64(offset, entry.createdAt, true);
+ offset += 8;
+
+ // accessedAt as float64 (little-endian)
+ view.setFloat64(offset, entry.accessedAt, true);
+ offset += 8;
+
+ // Access count as float64 (little-endian)
+ view.setFloat64(offset, entry.accessCount, true);
+ offset += 8;
+ }
+
+ // Ensure parent directory exists
+ const dir = dirname(this.cachePath);
+ if (!existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+
+ const tmpSuffix = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+ const tmpPath = this.cachePath + '.tmp.' + tmpSuffix;
+ writeFileSync(tmpPath, Buffer.from(buffer));
+ renameSync(tmpPath, this.cachePath);
+ this.dirty = false;
+ } catch (error) {
+ console.error(
+ '[rvf-embedding-cache] Flush error:',
+ error instanceof Error ? error.message : error
+ );
+ }
+ }
+
+ /**
+ * Load entries from the binary cache file.
+ */
+ private loadFromFile(): void {
+ try {
+ const fileBuffer = readFileSync(this.cachePath);
+ if (fileBuffer.length < MAGIC.length) return;
+
+ const buffer = fileBuffer.buffer.slice(
+ fileBuffer.byteOffset,
+ fileBuffer.byteOffset + fileBuffer.byteLength
+ );
+ const view = new DataView(buffer);
+ const bytes = new Uint8Array(buffer);
+ let offset = 0;
+
+ // Verify magic
+ for (let i = 0; i < MAGIC.length; i++) {
+ if (bytes[offset + i] !== MAGIC[i]) {
+ console.warn('[rvf-embedding-cache] Invalid magic bytes, skipping load');
+ return;
+ }
+ }
+ offset += MAGIC.length;
+
+ // Check for version header (v2+)
+ let formatVersion = 1;
+ if (offset + 4 <= buffer.byteLength) {
+ const possibleVersion = view.getUint32(offset, true);
+ if (possibleVersion === 2) {
+ formatVersion = possibleVersion;
+ offset += 4;
+ }
+ }
+
+ // Read entries
+ while (offset + 8 <= buffer.byteLength) {
+ // Need at least 4 (hash) + 4 (dims) = 8 bytes for the header
+ const hash = view.getUint32(offset, true);
+ offset += 4;
+
+ const dims = view.getUint32(offset, true);
+ offset += 4;
+
+ const entryDataSize = formatVersion === 2
+ ? dims * 4 + 8 + 8 + 8 // v2: embedding + createdAt + accessedAt + accessCount
+ : dims * 4 + 8 + 8; // v1: embedding + accessedAt + accessCount
+ if (offset + entryDataSize > buffer.byteLength) {
+ console.warn('[rvf-embedding-cache] Truncated entry, stopping load');
+ break;
+ }
+
+ // Read embedding
+ const embedding = new Float32Array(dims);
+ for (let i = 0; i < dims; i++) {
+ embedding[i] = view.getFloat32(offset, true);
+ offset += 4;
+ }
+
+ let createdAt: number;
+ let accessedAt: number;
+ let accessCount: number;
+
+ if (formatVersion >= 2) {
+ createdAt = view.getFloat64(offset, true);
+ offset += 8;
+ accessedAt = view.getFloat64(offset, true);
+ offset += 8;
+ accessCount = view.getFloat64(offset, true);
+ offset += 8;
+ } else {
+ // v1: only accessedAt was stored, use it as createdAt too
+ accessedAt = view.getFloat64(offset, true);
+ offset += 8;
+ accessCount = view.getFloat64(offset, true);
+ offset += 8;
+ createdAt = accessedAt;
+ }
+
+ this.entries.set(hash, {
+ embedding,
+ createdAt,
+ accessedAt,
+ accessCount,
+ });
+ }
+ } catch (error) {
+ console.warn(
+ '[rvf-embedding-cache] Load error:',
+ error instanceof Error ? error.message : error
+ );
+ }
+ }
+}
diff --git a/v3/@claude-flow/embeddings/src/rvf-embedding-service.ts b/v3/@claude-flow/embeddings/src/rvf-embedding-service.ts
new file mode 100644
index 0000000000..fd8297ceb7
--- /dev/null
+++ b/v3/@claude-flow/embeddings/src/rvf-embedding-service.ts
@@ -0,0 +1,377 @@
+/**
+ * RVF Embedding Service - Lightweight Hash-Based Embeddings
+ *
+ * Provides deterministic, sub-millisecond embedding generation using
+ * FNV-1a hash-based vectors. No neural model or external API required.
+ *
+ * Features:
+ * - Deterministic: same input always produces the same embedding
+ * - FNV-1a hash seeding with multi-round mixing
+ * - L2-normalized output vectors
+ * - Sub-millisecond generation (<0.1ms typical)
+ * - RvfEmbeddingCache for binary file persistence
+ * - Zero external dependencies
+ *
+ * Use cases:
+ * - Fast similarity search where relative distances matter more than semantics
+ * - Development and testing without API keys
+ * - Offline environments without neural model access
+ * - Bootstrapping before heavier providers are available
+ *
+ * @module @claude-flow/embeddings
+ */
+
+import { EventEmitter } from 'events';
+import type {
+ EmbeddingProvider,
+ EmbeddingResult,
+ BatchEmbeddingResult,
+ IEmbeddingService,
+ EmbeddingEvent,
+ EmbeddingEventListener,
+ NormalizationType,
+ RvfEmbeddingConfig,
+} from './types.js';
+import { normalize } from './normalization.js';
+import { RvfEmbeddingCache } from './rvf-embedding-cache.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** FNV-1a offset basis (32-bit) */
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+
+/** FNV-1a prime (32-bit) */
+const FNV_PRIME = 0x01000193;
+
+/** Default embedding dimensions */
+const DEFAULT_DIMENSIONS = 384;
+
+/** Default in-memory LRU cache size */
+const DEFAULT_CACHE_SIZE = 1000;
+
+// ============================================================================
+// LRU Cache (lightweight in-memory)
+// ============================================================================
+
+class LRUCache<K, V> {
+ private cache: Map<K, V> = new Map();
+ private hits = 0;
+ private misses = 0;
+
+ constructor(private readonly maxSize: number) {}
+
+ get(key: K): V | undefined {
+ const value = this.cache.get(key);
+ if (value !== undefined) {
+ // Move to end (most recently used)
+ this.cache.delete(key);
+ this.cache.set(key, value);
+ this.hits++;
+ return value;
+ }
+ this.misses++;
+ return undefined;
+ }
+
+ set(key: K, value: V): void {
+ if (this.cache.has(key)) {
+ this.cache.delete(key);
+ } else if (this.cache.size >= this.maxSize) {
+ const firstKey = this.cache.keys().next().value;
+ if (firstKey !== undefined) {
+ this.cache.delete(firstKey);
+ }
+ }
+ this.cache.set(key, value);
+ }
+
+ clear(): void {
+ this.cache.clear();
+ this.hits = 0;
+ this.misses = 0;
+ }
+
+ get size(): number {
+ return this.cache.size;
+ }
+
+ get hitRate(): number {
+ const total = this.hits + this.misses;
+ return total > 0 ? this.hits / total : 0;
+ }
+
+ getStats() {
+ return {
+ size: this.cache.size,
+ maxSize: this.maxSize,
+ hits: this.hits,
+ misses: this.misses,
+ hitRate: this.hitRate,
+ };
+ }
+}
+
+// ============================================================================
+// RVF Embedding Service
+// ============================================================================
+
+/**
+ * Lightweight hash-based embedding service.
+ *
+ * Generates deterministic embeddings from text using FNV-1a hashing
+ * with multi-round mixing and L2 normalization. The output is a unit
+ * vector in R^n where n = configured dimensions (default 384).
+ *
+ * Extends EventEmitter and implements IEmbeddingService for drop-in
+ * compatibility with other providers.
+ */
+export class RvfEmbeddingService extends EventEmitter implements IEmbeddingService {
+ readonly provider: EmbeddingProvider = 'rvf';
+
+ private readonly dimensions: number;
+ private readonly cache: LRUCache<string, Float32Array>;
+ private readonly normalizationType: NormalizationType;
+ private readonly embeddingListeners: Set<EmbeddingEventListener> = new Set();
+ private persistentCache: RvfEmbeddingCache | null = null;
+
+ constructor(config: RvfEmbeddingConfig) {
+ super();
+ this.dimensions = config.dimensions ?? DEFAULT_DIMENSIONS;
+ if (this.dimensions <= 0 || !Number.isInteger(this.dimensions)) {
+ throw new Error(`Invalid dimensions: ${this.dimensions}. Must be a positive integer.`);
+ }
+ this.cache = new LRUCache(config.cacheSize ?? DEFAULT_CACHE_SIZE);
+ this.normalizationType = config.normalization ?? 'none';
+
+ // Initialize persistent RVF cache if a path is provided
+ if (config.cachePath) {
+ this.persistentCache = new RvfEmbeddingCache({
+ cachePath: config.cachePath,
+ maxSize: config.cacheSize ?? 10000,
+ dimensions: this.dimensions,
+ });
+ }
+ }
+
+ // --------------------------------------------------------------------------
+ // IEmbeddingService Implementation
+ // --------------------------------------------------------------------------
+
+ /**
+ * Generate an embedding for a single text string.
+ */
+ async embed(text: string): Promise<EmbeddingResult> {
+ if (typeof text !== 'string') {
+ throw new Error('embed() expects a string argument');
+ }
+
+ // Check in-memory cache
+ const cached = this.cache.get(text);
+ if (cached) {
+ this.emitEvent({ type: 'cache_hit', text });
+ return { embedding: cached, latencyMs: 0, cached: true };
+ }
+
+ // Check persistent cache
+ if (this.persistentCache) {
+ const persisted = await this.persistentCache.get(text);
+ if (persisted) {
+ this.cache.set(text, persisted);
+ this.emitEvent({ type: 'cache_hit', text });
+ return { embedding: persisted, latencyMs: 0, cached: true, persistentCached: true };
+ }
+ }
+
+ this.emitEvent({ type: 'embed_start', text });
+ const startTime = performance.now();
+
+ // Generate deterministic embedding
+ const embedding = this.generateHashEmbedding(text);
+
+ // Apply optional normalization (hash embeddings are already L2-normalized,
+ // but the user may want a different normalization)
+ const normalized = this.applyNormalization(embedding);
+
+ // Store in caches
+ this.cache.set(text, normalized);
+ if (this.persistentCache) {
+ await this.persistentCache.set(text, normalized);
+ }
+
+ const latencyMs = performance.now() - startTime;
+ this.emitEvent({ type: 'embed_complete', text, latencyMs });
+
+ return { embedding: normalized, latencyMs };
+ }
+
+ /**
+ * Generate embeddings for multiple text strings.
+ */
+ async embedBatch(texts: string[]): Promise<BatchEmbeddingResult> {
+ if (!Array.isArray(texts)) {
+ throw new Error('embedBatch() expects an array of strings');
+ }
+
+ this.emitEvent({ type: 'batch_start', count: texts.length });
+ const startTime = performance.now();
+
+ const embeddings: Float32Array[] = [];
+ let cacheHits = 0;
+
+ for (const text of texts) {
+ const cached = this.cache.get(text);
+ if (cached) {
+ embeddings.push(cached);
+ cacheHits++;
+ this.emitEvent({ type: 'cache_hit', text });
+ continue;
+ }
+
+ // Check persistent cache
+ if (this.persistentCache) {
+ const persisted = await this.persistentCache.get(text);
+ if (persisted) {
+ this.cache.set(text, persisted);
+ embeddings.push(persisted);
+ cacheHits++;
+ this.emitEvent({ type: 'cache_hit', text });
+ continue;
+ }
+ }
+
+ const embedding = this.generateHashEmbedding(text);
+ const normalized = this.applyNormalization(embedding);
+ this.cache.set(text, normalized);
+
+ if (this.persistentCache) {
+ await this.persistentCache.set(text, normalized);
+ }
+
+ embeddings.push(normalized);
+ }
+
+ const totalLatencyMs = performance.now() - startTime;
+ this.emitEvent({ type: 'batch_complete', count: texts.length, latencyMs: totalLatencyMs });
+
+ return {
+ embeddings,
+ totalLatencyMs,
+ avgLatencyMs: totalLatencyMs / texts.length,
+ cacheStats: {
+ hits: cacheHits,
+ misses: texts.length - cacheHits,
+ },
+ };
+ }
+
+ clearCache(): void {
+ const size = this.cache.size;
+ this.cache.clear();
+ this.emitEvent({ type: 'cache_eviction', size });
+ }
+
+ getCacheStats() {
+ const stats = this.cache.getStats();
+ return {
+ size: stats.size,
+ maxSize: stats.maxSize,
+ hitRate: stats.hitRate,
+ };
+ }
+
+ async shutdown(): Promise<void> {
+ this.clearCache();
+ this.embeddingListeners.clear();
+ if (this.persistentCache) {
+ await this.persistentCache.close();
+ }
+ }
+
+ // --------------------------------------------------------------------------
+ // Event System
+ // --------------------------------------------------------------------------
+
+ addEventListener(listener: EmbeddingEventListener): void {
+ this.embeddingListeners.add(listener);
+ }
+
+ removeEventListener(listener: EmbeddingEventListener): void {
+ this.embeddingListeners.delete(listener);
+ }
+
+ private emitEvent(event: EmbeddingEvent): void {
+ for (const listener of this.embeddingListeners) {
+ try {
+ listener(event);
+ } catch (error) {
+ console.error('Error in embedding event listener:', error);
+ }
+ }
+ this.emit(event.type, event);
+ }
+
+ // --------------------------------------------------------------------------
+ // Hash Embedding Generation
+ // --------------------------------------------------------------------------
+
+ /**
+ * Generate a deterministic embedding from text using FNV-1a hashing.
+ *
+ * Algorithm:
+ * 1. Compute a base FNV-1a hash of the full text.
+ * 2. For each dimension, derive a unique seed by mixing the base hash
+ * with the dimension index using the golden ratio constant.
+ * 3. Apply a sine-based pseudo-random transform to spread values.
+ * 4. L2-normalize the result to produce a unit vector.
+ *
+ * This is deterministic: the same text always yields the same vector.
+ */
+ private generateHashEmbedding(text: string): Float32Array {
+ const embedding = new Float32Array(this.dimensions);
+
+ // Compute base FNV-1a hash of the full text
+ let baseHash = FNV_OFFSET_BASIS;
+ for (let i = 0; i < text.length; i++) {
+ baseHash ^= text.charCodeAt(i);
+ baseHash = Math.imul(baseHash, FNV_PRIME) >>> 0;
+ }
+
+ // Generate each dimension from a mixed seed
+ for (let i = 0; i < this.dimensions; i++) {
+ // Mix dimension index with the base hash using golden ratio constant
+ const seed = (baseHash + Math.imul(i, 0x9E3779B9)) >>> 0;
+ // Use sine for pseudo-random distribution in [-1, 1] range
+ const x = Math.sin(seed) * 43758.5453;
+ embedding[i] = x - Math.floor(x); // fractional part in [0, 1)
+ // Shift to [-0.5, 0.5) for zero-centered distribution
+ embedding[i] -= 0.5;
+ }
+
+ // L2 normalize to unit vector
+ let norm = 0;
+ for (let i = 0; i < this.dimensions; i++) {
+ norm += embedding[i] * embedding[i];
+ }
+ norm = Math.sqrt(norm);
+
+ if (norm > 0) {
+ for (let i = 0; i < this.dimensions; i++) {
+ embedding[i] /= norm;
+ }
+ }
+
+ return embedding;
+ }
+
+ /**
+ * Apply user-configured normalization if set.
+ */
+ private applyNormalization(embedding: Float32Array): Float32Array {
+ if (this.normalizationType === 'none') {
+ return embedding;
+ }
+ return normalize(embedding, { type: this.normalizationType });
+ }
+}
diff --git a/v3/@claude-flow/embeddings/src/types.ts b/v3/@claude-flow/embeddings/src/types.ts
index e7be361cae..1bbf65123b 100644
--- a/v3/@claude-flow/embeddings/src/types.ts
+++ b/v3/@claude-flow/embeddings/src/types.ts
@@ -19,7 +19,7 @@
/**
* Supported embedding providers
*/
-export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow';
+export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow' | 'rvf';
/**
* Normalization type for embeddings
@@ -144,6 +144,23 @@ export interface AgenticFlowEmbeddingConfig extends EmbeddingBaseConfig {
autoDownload?: boolean;
}
+/**
+ * RVF provider configuration
+ * Lightweight hash-based embeddings (no neural model, sub-ms latency)
+ */
+export interface RvfEmbeddingConfig extends EmbeddingBaseConfig {
+ provider: 'rvf';
+
+ /** Embedding dimensions (default: 384) */
+ dimensions?: number;
+
+ /** Path to binary cache file for persistent storage */
+ cachePath?: string;
+
+ /** Similarity metric preference (default: 'cosine') */
+ metric?: 'cosine' | 'l2' | 'dotproduct';
+}
+
/**
* Union of all provider configs
*/
@@ -151,7 +168,8 @@ export type EmbeddingConfig =
| OpenAIEmbeddingConfig
| TransformersEmbeddingConfig
| MockEmbeddingConfig
- | AgenticFlowEmbeddingConfig;
+ | AgenticFlowEmbeddingConfig
+ | RvfEmbeddingConfig;
// ============================================================================
// Result Types
diff --git a/v3/@claude-flow/memory/src/database-provider.ts b/v3/@claude-flow/memory/src/database-provider.ts
index ca1890fec2..b647d2c004 100644
--- a/v3/@claude-flow/memory/src/database-provider.ts
+++ b/v3/@claude-flow/memory/src/database-provider.ts
@@ -28,7 +28,7 @@ import { SqlJsBackend, SqlJsBackendConfig } from './sqljs-backend.js';
/**
* Available database provider types
*/
-export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'auto';
+export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'rvf' | 'auto';
/**
* Database creation options
@@ -91,6 +91,13 @@ function detectPlatform(): PlatformInfo {
};
}
+/**
+ * Test if RVF backend is available (always true β€” pure-TS fallback)
+ */
+async function testRvf(): Promise<boolean> {
+ return true;
+}
+
/**
* Test if better-sqlite3 is available and working
*/
@@ -141,7 +148,15 @@ async function selectProvider(
console.log(`[DatabaseProvider] Recommended provider: ${platformInfo.recommendedProvider}`);
}
- // Try recommended provider first
+ // Try RVF first (always available via pure-TS fallback, native when @ruvector/rvf installed)
+ if (await testRvf()) {
+ if (verbose) {
+ console.log('[DatabaseProvider] RVF backend available');
+ }
+ return 'rvf';
+ }
+
+ // Try recommended provider
if (platformInfo.recommendedProvider === 'better-sqlite3') {
if (await testBetterSqlite3()) {
if (verbose) {
@@ -247,6 +262,18 @@ export async function createDatabase(
break;
}
+ case 'rvf': {
+ const { RvfBackend } = await import('./rvf-backend.js');
+ backend = new RvfBackend({
+ databasePath: path.replace(/\.(db|json)$/, '.rvf'),
+ dimensions: 1536,
+ verbose,
+ defaultNamespace,
+ autoPersistInterval,
+ });
+ break;
+ }
+
case 'json': {
// Simple JSON file backend (minimal implementation)
backend = new JsonBackend(path, verbose);
@@ -278,14 +305,16 @@ export function getPlatformInfo(): PlatformInfo {
* Check which providers are available
*/
export async function getAvailableProviders(): Promise<{
+ rvf: boolean;
betterSqlite3: boolean;
sqlJs: boolean;
json: boolean;
}> {
return {
+ rvf: true,
betterSqlite3: await testBetterSqlite3(),
sqlJs: await testSqlJs(),
- json: true, // Always available
+ json: true,
};
}
diff --git a/v3/@claude-flow/memory/src/hnsw-lite.ts b/v3/@claude-flow/memory/src/hnsw-lite.ts
new file mode 100644
index 0000000000..a51c817e6b
--- /dev/null
+++ b/v3/@claude-flow/memory/src/hnsw-lite.ts
@@ -0,0 +1,190 @@
+export interface HnswSearchResult {
+ id: string;
+ score: number;
+}
+
+export class HnswLite {
+ private vectors = new Map<string, Float32Array>();
+ private neighbors = new Map<string, Set<string>>();
+ private readonly dimensions: number;
+ private readonly maxNeighbors: number;
+ private readonly efConstruction: number;
+ private readonly metric: string;
+
+ constructor(dimensions: number, m: number, efConstruction: number, metric: string) {
+ this.dimensions = dimensions;
+ this.maxNeighbors = m;
+ this.efConstruction = efConstruction;
+ this.metric = metric;
+ }
+
+ get size(): number {
+ return this.vectors.size;
+ }
+
+ add(id: string, vector: Float32Array): void {
+ this.vectors.set(id, vector);
+
+ if (this.vectors.size === 1) {
+ this.neighbors.set(id, new Set());
+ return;
+ }
+
+ const nearest = this.findNearest(vector, this.maxNeighbors);
+ const neighborSet = new Set<string>();
+
+ for (const n of nearest) {
+ neighborSet.add(n.id);
+ const nNeighbors = this.neighbors.get(n.id);
+ if (nNeighbors) {
+ nNeighbors.add(id);
+ if (nNeighbors.size > this.maxNeighbors * 2) {
+ this.pruneNeighbors(n.id);
+ }
+ }
+ }
+
+ this.neighbors.set(id, neighborSet);
+ }
+
+ remove(id: string): void {
+ this.vectors.delete(id);
+ const myNeighbors = this.neighbors.get(id);
+ if (myNeighbors) {
+ for (const nId of myNeighbors) {
+ this.neighbors.get(nId)?.delete(id);
+ }
+ }
+ this.neighbors.delete(id);
+ }
+
+ search(query: Float32Array, k: number, threshold?: number): HnswSearchResult[] {
+ if (this.vectors.size === 0) return [];
+ if (this.vectors.size <= k * 2) {
+ return this.bruteForce(query, k, threshold);
+ }
+
+ const visited = new Set<string>();
+ const candidates: HnswSearchResult[] = [];
+
+ let entryId: string | undefined;
+ let bestScore = -1;
+ for (const [id] of this.vectors) {
+ const score = this.similarity(query, this.vectors.get(id)!);
+ if (score > bestScore) {
+ bestScore = score;
+ entryId = id;
+ }
+ if (visited.size >= Math.min(this.efConstruction, this.vectors.size)) break;
+ visited.add(id);
+ candidates.push({ id, score });
+ }
+
+ if (entryId) {
+ const queue = [entryId];
+ let idx = 0;
+
+ while (idx < queue.length && visited.size < this.efConstruction * 2) {
+ const currentId = queue[idx++];
+ const currentNeighbors = this.neighbors.get(currentId);
+ if (!currentNeighbors) continue;
+
+ for (const nId of currentNeighbors) {
+ if (visited.has(nId)) continue;
+ visited.add(nId);
+
+ const vec = this.vectors.get(nId);
+ if (!vec) continue;
+
+ const score = this.similarity(query, vec);
+ candidates.push({ id: nId, score });
+ queue.push(nId);
+ }
+ }
+ }
+
+ candidates.sort((a, b) => b.score - a.score);
+
+ let filtered = candidates;
+ if (threshold !== undefined) {
+ filtered = filtered.filter(c => c.score >= threshold);
+ }
+
+ return filtered.slice(0, k);
+ }
+
+ private bruteForce(query: Float32Array, k: number, threshold?: number): HnswSearchResult[] {
+ const results: HnswSearchResult[] = [];
+ for (const [id, vec] of this.vectors) {
+ const score = this.similarity(query, vec);
+ if (threshold !== undefined && score < threshold) continue;
+ results.push({ id, score });
+ }
+ results.sort((a, b) => b.score - a.score);
+ return results.slice(0, k);
+ }
+
+ private findNearest(query: Float32Array, k: number): HnswSearchResult[] {
+ return this.bruteForce(query, k);
+ }
+
+ private pruneNeighbors(id: string): void {
+ const myNeighbors = this.neighbors.get(id);
+ if (!myNeighbors) return;
+
+ const vec = this.vectors.get(id);
+ if (!vec) return;
+
+ const scored: HnswSearchResult[] = [];
+ for (const nId of myNeighbors) {
+ const nVec = this.vectors.get(nId);
+ if (!nVec) continue;
+ scored.push({ id: nId, score: this.similarity(vec, nVec) });
+ }
+
+ scored.sort((a, b) => b.score - a.score);
+ const keep = new Set(scored.slice(0, this.maxNeighbors).map(s => s.id));
+
+ for (const nId of myNeighbors) {
+ if (!keep.has(nId)) {
+ myNeighbors.delete(nId);
+ }
+ }
+ }
+
+ private similarity(a: Float32Array, b: Float32Array): number {
+ if (this.metric === 'dot') return dotProduct(a, b);
+ if (this.metric === 'euclidean') return 1 / (1 + euclideanDistance(a, b));
+ return cosineSimilarity(a, b);
+ }
+}
+
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+ let dot = 0;
+ let normA = 0;
+ let normB = 0;
+ for (let i = 0; i < a.length; i++) {
+ dot += a[i] * b[i];
+ normA += a[i] * a[i];
+ normB += b[i] * b[i];
+ }
+ if (normA === 0 || normB === 0) return 0;
+ return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+function dotProduct(a: Float32Array, b: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) {
+ sum += a[i] * b[i];
+ }
+ return sum;
+}
+
+function euclideanDistance(a: Float32Array, b: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) {
+ const d = a[i] - b[i];
+ sum += d * d;
+ }
+ return Math.sqrt(sum);
+}
diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.ts
index a20b2d5a3d..7bbdcef6de 100644
--- a/v3/@claude-flow/memory/src/index.ts
+++ b/v3/@claude-flow/memory/src/index.ts
@@ -124,6 +124,22 @@ export type {
PatternMatch,
} from './learning-bridge.js';
+// ===== RVF Learning Persistence (ADR-057 Phase 6) =====
+export { RvfLearningStore } from './rvf-learning-store.js';
+export type {
+ RvfLearningStoreConfig,
+ PatternRecord,
+ LoraRecord,
+ EwcRecord,
+ TrajectoryRecord,
+} from './rvf-learning-store.js';
+export { PersistentSonaCoordinator } from './persistent-sona.js';
+export type { PersistentSonaConfig } from './persistent-sona.js';
+
+// ===== RVF Migration (Bidirectional) =====
+export { RvfMigrator } from './rvf-migration.js';
+export type { RvfMigrationOptions, RvfMigrationResult } from './rvf-migration.js';
+
// ===== Knowledge Graph =====
export { MemoryGraph } from './memory-graph.js';
export type {
@@ -177,6 +193,10 @@ export type {
SemanticQuery,
HybridQuery,
} from './hybrid-backend.js';
+export { RvfBackend } from './rvf-backend.js';
+export type { RvfBackendConfig } from './rvf-backend.js';
+export { HnswLite, cosineSimilarity } from './hnsw-lite.js';
+export type { HnswSearchResult } from './hnsw-lite.js';
export { HNSWIndex } from './hnsw-index.js';
export { CacheManager, TieredCacheManager } from './cache-manager.js';
export { QueryBuilder, query, QueryTemplates } from './query-builder.js';
diff --git a/v3/@claude-flow/memory/src/persistent-sona.ts b/v3/@claude-flow/memory/src/persistent-sona.ts
new file mode 100644
index 0000000000..2b27ebd921
--- /dev/null
+++ b/v3/@claude-flow/memory/src/persistent-sona.ts
@@ -0,0 +1,439 @@
+/**
+ * PersistentSonaCoordinator - SONA learning with RVF persistence
+ *
+ * Wraps RvfLearningStore to provide an in-memory pattern bank with
+ * brute-force cosine similarity, trajectory buffering, EWC tracking,
+ * and automatic periodic persistence to disk.
+ *
+ * This is intentionally decoupled from the ruvector SONA classes:
+ * it defines its own compatible types and delegates persistence to
+ * RvfLearningStore.
+ *
+ * @module @claude-flow/memory/persistent-sona
+ */
+
+import {
+ RvfLearningStore,
+} from './rvf-learning-store.js';
+import type {
+ RvfLearningStoreConfig,
+ PatternRecord,
+ EwcRecord,
+ TrajectoryRecord,
+} from './rvf-learning-store.js';
+
+// ===== Types =====
+
+export interface PersistentSonaConfig {
+ /** Path to the RVF learning store file */
+ storePath: string;
+ /** Cosine similarity threshold for pattern matching (default: 0.85) */
+ patternThreshold?: number;
+ /** Maximum buffered trajectories before oldest are evicted (default: 1000) */
+ maxTrajectoryBuffer?: number;
+ /** Auto-persist interval in ms (default: 30000) */
+ autoPersistInterval?: number;
+ /** Enable verbose logging (default: false) */
+ verbose?: boolean;
+}
+
+// ===== Constants =====
+
+const DEFAULT_PATTERN_THRESHOLD = 0.85;
+const DEFAULT_MAX_TRAJECTORY_BUFFER = 1000;
+const DEFAULT_AUTO_PERSIST_MS = 30_000;
+
+// ===== Helpers =====
+
+/**
+ * Compute cosine similarity between two number arrays.
+ * Returns 0 when either vector has zero magnitude.
+ */
+function cosineSimilarity(a: number[], b: number[]): number {
+ const len = Math.min(a.length, b.length);
+ let dot = 0;
+ let normA = 0;
+ let normB = 0;
+
+ // Process in groups of 4 for better throughput
+ let i = 0;
+ for (; i + 3 < len; i += 4) {
+ dot += a[i] * b[i] + a[i + 1] * b[i + 1] + a[i + 2] * b[i + 2] + a[i + 3] * b[i + 3];
+ normA += a[i] * a[i] + a[i + 1] * a[i + 1] + a[i + 2] * a[i + 2] + a[i + 3] * a[i + 3];
+ normB += b[i] * b[i] + b[i + 1] * b[i + 1] + b[i + 2] * b[i + 2] + b[i + 3] * b[i + 3];
+ }
+ for (; i < len; i++) {
+ dot += a[i] * b[i];
+ normA += a[i] * a[i];
+ normB += b[i] * b[i];
+ }
+
+ const denom = Math.sqrt(normA) * Math.sqrt(normB);
+ return denom > 0 ? dot / denom : 0;
+}
+
+function generateId(prefix: string): string {
+ return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ===== PersistentSonaCoordinator =====
+
+/**
+ * Coordinates SONA learning with persistent storage.
+ *
+ * @example
+ * ```typescript
+ * const sona = new PersistentSonaCoordinator({
+ * storePath: './data/sona-learning.rvls',
+ * });
+ * await sona.initialize();
+ *
+ * // Store a pattern
+ * const id = sona.storePattern('query_response', embedding);
+ *
+ * // Find similar patterns
+ * const matches = sona.findSimilarPatterns(queryEmbedding, 5);
+ *
+ * // Record a trajectory
+ * sona.recordTrajectory({ id: 'traj-1', steps: [...], outcome: 'success', ... });
+ *
+ * // Periodic background learning
+ * const result = sona.runBackgroundLoop();
+ *
+ * await sona.shutdown();
+ * ```
+ */
+export class PersistentSonaCoordinator {
+ private store: RvfLearningStore;
+ private patterns: Map<string, PatternRecord> = new Map();
+ private trajectoryBuffer: TrajectoryRecord[] = [];
+ private ewcState: EwcRecord | null = null;
+ private patternThreshold: number;
+ private maxTrajectoryBuffer: number;
+ private verbose: boolean;
+ private initialized = false;
+
+ constructor(config: PersistentSonaConfig) {
+ this.patternThreshold = config.patternThreshold ?? DEFAULT_PATTERN_THRESHOLD;
+ this.maxTrajectoryBuffer = config.maxTrajectoryBuffer ?? DEFAULT_MAX_TRAJECTORY_BUFFER;
+ this.verbose = config.verbose ?? false;
+
+ const storeConfig: RvfLearningStoreConfig = {
+ storePath: config.storePath,
+ autoPersistInterval: config.autoPersistInterval ?? DEFAULT_AUTO_PERSIST_MS,
+ verbose: config.verbose,
+ };
+
+ this.store = new RvfLearningStore(storeConfig);
+ }
+
+ /**
+ * Initialize by loading persisted state from the RVF store.
+ */
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ await this.store.initialize();
+
+ // Rebuild in-memory state from store
+ const patterns = await this.store.loadPatterns();
+ for (const p of patterns) {
+ this.patterns.set(p.id, p);
+ }
+
+ const ewc = await this.store.loadEwcState();
+ this.ewcState = ewc;
+
+ const trajectories = await this.store.getTrajectories();
+ // getTrajectories returns newest-first, reverse for chronological buffer
+ this.trajectoryBuffer = trajectories.reverse();
+
+ this.initialized = true;
+ this.log(
+ `Initialized: ${this.patterns.size} patterns, ` +
+ `${this.trajectoryBuffer.length} trajectories, ` +
+ `EWC: ${this.ewcState ? 'yes' : 'no'}`,
+ );
+ }
+
+ // ===== Pattern operations =====
+
+ /**
+ * Store a new pattern and return its ID.
+ *
+ * @param type - Pattern type (e.g. 'query_response', 'routing')
+ * @param embedding - The pattern embedding vector
+ * @param metadata - Optional extra metadata (currently unused, reserved)
+ * @returns The generated pattern ID
+ */
+ storePattern(
+ type: string,
+ embedding: number[],
+ metadata?: Record<string, unknown>,
+ ): string {
+ this.ensureInitialized();
+
+ const id = generateId('pat');
+ const record: PatternRecord = {
+ id,
+ type,
+ embedding: [...embedding],
+ successRate: 1.0,
+ useCount: 0,
+ lastUsed: new Date().toISOString(),
+ };
+
+ this.patterns.set(id, record);
+ // Mark for persistence on next persist() call
+ void this.store.savePatterns([record]).catch(() => {});
+ return id;
+ }
+
+ /**
+ * Find the k most similar patterns above the configured threshold.
+ * Uses brute-force cosine similarity (suitable for small pattern sets).
+ */
+ findSimilarPatterns(embedding: number[], k: number = 5): PatternRecord[] {
+ this.ensureInitialized();
+
+ const results: Array<{ record: PatternRecord; score: number }> = [];
+
+ for (const record of this.patterns.values()) {
+ const score = cosineSimilarity(embedding, record.embedding);
+ if (score >= this.patternThreshold) {
+ results.push({ record, score });
+ }
+ }
+
+ // Sort descending by score and take top-k
+ results.sort((a, b) => b.score - a.score);
+
+ return results.slice(0, k).map((r) => r.record);
+ }
+
+ /**
+ * Record a pattern usage outcome. Updates the success rate using an
+ * exponential moving average (alpha = 0.1).
+ */
+ recordPatternUsage(patternId: string, success: boolean): void {
+ this.ensureInitialized();
+
+ const pattern = this.patterns.get(patternId);
+ if (!pattern) return;
+
+ pattern.useCount++;
+ pattern.lastUsed = new Date().toISOString();
+
+ const alpha = 0.1;
+ const outcome = success ? 1.0 : 0.0;
+ pattern.successRate = alpha * outcome + (1 - alpha) * pattern.successRate;
+ }
+
+ /**
+ * Remove patterns that have low success rates after sufficient usage.
+ *
+ * @returns The number of patterns pruned
+ */
+ prunePatterns(minSuccessRate: number = 0.3, minUseCount: number = 5): number {
+ this.ensureInitialized();
+
+ let pruned = 0;
+ for (const [id, pattern] of this.patterns) {
+ if (pattern.useCount >= minUseCount && pattern.successRate < minSuccessRate) {
+ this.patterns.delete(id);
+ pruned++;
+ }
+ }
+
+ if (pruned > 0) {
+ this.log(`Pruned ${pruned} low-performing patterns`);
+ }
+
+ return pruned;
+ }
+
+ // ===== Trajectory tracking =====
+
+ /**
+ * Buffer a completed trajectory for later processing.
+ * When the buffer exceeds maxTrajectoryBuffer, the oldest entries
+ * are evicted.
+ */
+ recordTrajectory(trajectory: TrajectoryRecord): void {
+ this.ensureInitialized();
+
+ const copy = { ...trajectory };
+ this.trajectoryBuffer.push(copy);
+
+ // Persist to store immediately so evicted entries are not lost
+ void this.store.appendTrajectory(copy).catch(() => {});
+
+ while (this.trajectoryBuffer.length > this.maxTrajectoryBuffer) {
+ this.trajectoryBuffer.shift();
+ }
+ }
+
+ // ===== Learning loop =====
+
+ /**
+ * Process buffered trajectories to extract new patterns.
+ * Successful and partial trajectories are mined for high-confidence
+ * steps; new patterns are stored if they are sufficiently different
+ * from existing ones.
+ *
+ * After processing, the trajectory buffer is cleared and low-performing
+ * patterns are pruned.
+ *
+ * @returns Summary of the learning pass
+ */
+ runBackgroundLoop(): {
+ patternsLearned: number;
+ trajectoriesProcessed: number;
+ } {
+ this.ensureInitialized();
+
+ let patternsLearned = 0;
+ const trajectoriesProcessed = this.trajectoryBuffer.length;
+
+ for (const traj of this.trajectoryBuffer) {
+ if (traj.outcome === 'success' || traj.outcome === 'partial') {
+ patternsLearned += this.extractPatternsFromTrajectory(traj);
+ }
+ }
+
+ this.prunePatterns();
+ this.trajectoryBuffer = [];
+
+ this.log(
+ `Background loop: ${patternsLearned} patterns learned, ` +
+ `${trajectoriesProcessed} trajectories processed`,
+ );
+
+ return { patternsLearned, trajectoriesProcessed };
+ }
+
+ // ===== Persistence =====
+
+ /**
+ * Flush current in-memory state to the RVF store on disk.
+ */
+ async persist(): Promise<void> {
+ const allPatterns = Array.from(this.patterns.values());
+ await this.store.savePatterns(allPatterns);
+
+ if (this.ewcState) {
+ await this.store.saveEwcState(this.ewcState);
+ }
+
+ // Persist any buffered trajectories that have not yet been saved
+ for (const traj of this.trajectoryBuffer) {
+ await this.store.appendTrajectory(traj);
+ }
+
+ await this.store.persist();
+ }
+
+ /**
+ * Persist state and shut down the store.
+ */
+ async shutdown(): Promise<void> {
+ if (!this.initialized) return;
+
+ await this.persist();
+ await this.store.close();
+ this.initialized = false;
+ this.log('Shutdown complete');
+ }
+
+ // ===== Stats =====
+
+ /**
+ * Return a summary of the coordinator's current state.
+ */
+ getStats(): {
+ patterns: number;
+ avgSuccessRate: number;
+ trajectoriesBuffered: number;
+ ewcTasksLearned: number;
+ } {
+ let totalSuccessRate = 0;
+ let count = 0;
+ for (const p of this.patterns.values()) {
+ totalSuccessRate += p.successRate;
+ count++;
+ }
+
+ return {
+ patterns: this.patterns.size,
+ avgSuccessRate: count > 0 ? totalSuccessRate / count : 0,
+ trajectoriesBuffered: this.trajectoryBuffer.length,
+ ewcTasksLearned: this.ewcState?.tasksLearned ?? 0,
+ };
+ }
+
+ // ===== Private =====
+
+ /**
+ * Extract patterns from a trajectory's high-confidence steps.
+ * A step produces a new pattern only if no sufficiently similar
+ * pattern already exists.
+ */
+ private extractPatternsFromTrajectory(trajectory: TrajectoryRecord): number {
+ let extracted = 0;
+
+ for (const step of trajectory.steps) {
+ if (step.confidence < this.patternThreshold) continue;
+
+ const embedding = this.createHashEmbedding(step.input + step.output);
+ const similar = this.findSimilarPatterns(embedding, 1);
+
+ if (similar.length === 0) {
+ this.storePattern(step.type, embedding);
+ extracted++;
+ }
+ }
+
+ return extracted;
+ }
+
+ /**
+ * Deterministic hash-based embedding for pattern extraction.
+ * This is a lightweight stand-in for a real embedding model,
+ * matching the approach used in SonaCoordinator.
+ */
+ private createHashEmbedding(text: string, dim: number = 64): number[] {
+ const embedding = new Array<number>(dim).fill(0);
+
+ for (let i = 0; i < text.length; i++) {
+ const idx = (text.charCodeAt(i) * (i + 1)) % dim;
+ embedding[idx] += 0.1;
+ }
+
+ let norm = 0;
+ for (let i = 0; i < dim; i++) {
+ norm += embedding[i] * embedding[i];
+ }
+ norm = Math.sqrt(norm) || 1;
+
+ for (let i = 0; i < dim; i++) {
+ embedding[i] /= norm;
+ }
+
+ return embedding;
+ }
+
+ private ensureInitialized(): void {
+ if (!this.initialized) {
+ throw new Error(
+ 'PersistentSonaCoordinator has not been initialized. Call initialize() first.',
+ );
+ }
+ }
+
+ private log(message: string): void {
+ if (this.verbose) {
+ // eslint-disable-next-line no-console
+ console.log(`[PersistentSona] ${message}`);
+ }
+ }
+}
diff --git a/v3/@claude-flow/memory/src/rvf-backend.ts b/v3/@claude-flow/memory/src/rvf-backend.ts
new file mode 100644
index 0000000000..7b2ac986dd
--- /dev/null
+++ b/v3/@claude-flow/memory/src/rvf-backend.ts
@@ -0,0 +1,518 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import type {
+ IMemoryBackend,
+ MemoryEntry,
+ MemoryEntryUpdate,
+ MemoryQuery,
+ SearchOptions,
+ SearchResult,
+ BackendStats,
+ HealthCheckResult,
+ MemoryType,
+} from './types.js';
+import { HnswLite, cosineSimilarity } from './hnsw-lite.js';
+
+/** Validate a file path is safe (no null bytes, no traversal above root) */
+function validatePath(p: string): void {
+ if (p === ':memory:') return;
+ if (p.includes('\0')) throw new Error('Path contains null bytes');
+ const resolved = resolve(p);
+ if (resolved.includes('\0')) throw new Error('Resolved path contains null bytes');
+}
+
+export interface RvfBackendConfig {
+ databasePath: string;
+ dimensions?: number;
+ metric?: 'cosine' | 'euclidean' | 'dot';
+ quantization?: 'fp32' | 'fp16' | 'int8';
+ hnswM?: number;
+ hnswEfConstruction?: number;
+ maxElements?: number;
+ verbose?: boolean;
+ defaultNamespace?: string;
+ autoPersistInterval?: number;
+}
+
+interface RvfHeader {
+ magic: string;
+ version: number;
+ dimensions: number;
+ metric: string;
+ quantization: string;
+ entryCount: number;
+ createdAt: number;
+ updatedAt: number;
+}
+
+const MAGIC = 'RVF\0';
+const VERSION = 1;
+const DEFAULT_DIMENSIONS = 1536;
+const DEFAULT_M = 16;
+const DEFAULT_EF_CONSTRUCTION = 200;
+const DEFAULT_MAX_ELEMENTS = 100000;
+const DEFAULT_PERSIST_INTERVAL = 30000;
+
+export class RvfBackend implements IMemoryBackend {
+ private entries = new Map<string, MemoryEntry>();
+ private keyIndex = new Map<string, string>();
+ private hnswIndex: HnswLite | null = null;
+ private nativeDb: any = null;
+ private config: Required<RvfBackendConfig>;
+ private initialized = false;
+ private dirty = false;
+ private persisting = false;
+ private persistTimer: ReturnType<typeof setInterval> | null = null;
+ private queryTimes: number[] = [];
+ private searchTimes: number[] = [];
+
+ constructor(config: RvfBackendConfig) {
+ const dimensions = config.dimensions ?? DEFAULT_DIMENSIONS;
+ if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 10000) {
+ throw new Error(`Invalid dimensions: ${dimensions}. Must be an integer between 1 and 10000.`);
+ }
+ this.config = {
+ databasePath: config.databasePath,
+ dimensions,
+ metric: config.metric ?? 'cosine',
+ quantization: config.quantization ?? 'fp32',
+ hnswM: config.hnswM ?? DEFAULT_M,
+ hnswEfConstruction: config.hnswEfConstruction ?? DEFAULT_EF_CONSTRUCTION,
+ maxElements: config.maxElements ?? DEFAULT_MAX_ELEMENTS,
+ verbose: config.verbose ?? false,
+ defaultNamespace: config.defaultNamespace ?? 'default',
+ autoPersistInterval: config.autoPersistInterval ?? DEFAULT_PERSIST_INTERVAL,
+ };
+ validatePath(this.config.databasePath);
+ }
+
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ const useNative = await this.tryNativeInit();
+ if (!useNative) {
+ this.hnswIndex = new HnswLite(
+ this.config.dimensions,
+ this.config.hnswM,
+ this.config.hnswEfConstruction,
+ this.config.metric,
+ );
+ await this.loadFromDisk();
+ }
+
+ if (this.config.autoPersistInterval > 0 && this.config.databasePath !== ':memory:') {
+ this.persistTimer = setInterval(() => {
+ if (this.dirty && !this.persisting) this.persistToDisk().catch(() => {});
+ }, this.config.autoPersistInterval);
+ if (this.persistTimer.unref) this.persistTimer.unref();
+ }
+
+ this.initialized = true;
+ if (this.config.verbose) {
+ const mode = this.nativeDb ? 'native @ruvector/rvf' : 'pure-TS fallback';
+ console.log(`[RvfBackend] Initialized (${mode}), ${this.entries.size} entries loaded`);
+ }
+ }
+
+ async shutdown(): Promise<void> {
+ if (!this.initialized) return;
+
+ if (this.persistTimer) {
+ clearInterval(this.persistTimer);
+ this.persistTimer = null;
+ }
+
+ if (this.dirty) {
+ await this.persistToDisk();
+ }
+
+ if (this.nativeDb) {
+ try { await this.nativeDb.close(); } catch {}
+ this.nativeDb = null;
+ }
+
+ this.entries.clear();
+ this.keyIndex.clear();
+ this.hnswIndex = null;
+ this.initialized = false;
+ }
+
+ async store(entry: MemoryEntry): Promise<void> {
+ const ns = entry.namespace || this.config.defaultNamespace;
+ const e = ns !== entry.namespace ? { ...entry, namespace: ns } : entry;
+ this.entries.set(e.id, e);
+ this.keyIndex.set(this.compositeKey(e.namespace, e.key), e.id);
+ if (e.embedding && this.hnswIndex) {
+ this.hnswIndex.add(e.id, e.embedding);
+ }
+ this.dirty = true;
+ }
+
+ async get(id: string): Promise<MemoryEntry | null> {
+ const entry = this.entries.get(id);
+ if (!entry) return null;
+ entry.accessCount++;
+ entry.lastAccessedAt = Date.now();
+ return entry;
+ }
+
+ async getByKey(namespace: string, key: string): Promise<MemoryEntry | null> {
+ const id = this.keyIndex.get(this.compositeKey(namespace, key));
+ if (!id) return null;
+ return this.get(id);
+ }
+
+ async update(id: string, updateData: MemoryEntryUpdate): Promise<MemoryEntry | null> {
+ const entry = this.entries.get(id);
+ if (!entry) return null;
+
+ const updated: MemoryEntry = {
+ ...entry,
+ ...updateData,
+ updatedAt: Date.now(),
+ version: entry.version + 1,
+ };
+ this.entries.set(id, updated);
+ this.dirty = true;
+ return updated;
+ }
+
+ async delete(id: string): Promise<boolean> {
+ const entry = this.entries.get(id);
+ if (!entry) return false;
+ this.entries.delete(id);
+ this.keyIndex.delete(this.compositeKey(entry.namespace, entry.key));
+ if (this.hnswIndex) this.hnswIndex.remove(id);
+ this.dirty = true;
+ return true;
+ }
+
+ async query(q: MemoryQuery): Promise<MemoryEntry[]> {
+ const start = performance.now();
+ let results = Array.from(this.entries.values());
+
+ if (q.namespace) results = results.filter(e => e.namespace === q.namespace);
+ if (q.key) results = results.filter(e => e.key === q.key);
+ if (q.keyPrefix) results = results.filter(e => e.key.startsWith(q.keyPrefix!));
+ if (q.tags?.length) results = results.filter(e => q.tags!.every(t => e.tags.includes(t)));
+ if (q.memoryType) results = results.filter(e => e.type === q.memoryType);
+ if (q.accessLevel) results = results.filter(e => e.accessLevel === q.accessLevel);
+ if (q.ownerId) results = results.filter(e => e.ownerId === q.ownerId);
+ if (q.createdAfter) results = results.filter(e => e.createdAt > q.createdAfter!);
+ if (q.createdBefore) results = results.filter(e => e.createdAt < q.createdBefore!);
+ if (q.updatedAfter) results = results.filter(e => e.updatedAt > q.updatedAfter!);
+ if (q.updatedBefore) results = results.filter(e => e.updatedAt < q.updatedBefore!);
+ if (!q.includeExpired) {
+ const now = Date.now();
+ results = results.filter(e => !e.expiresAt || e.expiresAt > now);
+ }
+
+ if (q.type === 'semantic' && q.embedding && this.hnswIndex) {
+ const searchResults = this.hnswIndex.search(q.embedding, q.limit, q.threshold);
+ const idSet = new Set(searchResults.map(r => r.id));
+ results = results.filter(e => idSet.has(e.id));
+ }
+
+ const offset = q.offset ?? 0;
+ results = results.slice(offset, offset + q.limit);
+
+ this.recordTiming(this.queryTimes, start);
+ return results;
+ }
+
+ async search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]> {
+ const start = performance.now();
+ let results: SearchResult[];
+
+ if (this.hnswIndex) {
+ const raw = this.hnswIndex.search(embedding, options.k * 2, options.threshold);
+ results = [];
+ for (const r of raw) {
+ const entry = this.entries.get(r.id);
+ if (!entry) continue;
+ if (options.filters?.namespace && entry.namespace !== options.filters.namespace) continue;
+ if (options.filters?.tags && !options.filters.tags.every(t => entry.tags.includes(t))) continue;
+ if (options.filters?.memoryType && entry.type !== options.filters.memoryType) continue;
+ results.push({ entry, score: r.score, distance: 1 - r.score });
+ }
+ results = results.slice(0, options.k);
+ } else {
+ results = this.bruteForceSearch(embedding, options);
+ }
+
+ this.recordTiming(this.searchTimes, start);
+ return results;
+ }
+
+ async bulkInsert(entries: MemoryEntry[]): Promise<void> {
+ for (const entry of entries) {
+ this.entries.set(entry.id, entry);
+ this.keyIndex.set(this.compositeKey(entry.namespace, entry.key), entry.id);
+ if (entry.embedding && this.hnswIndex) this.hnswIndex.add(entry.id, entry.embedding);
+ }
+ this.dirty = true;
+ }
+
+ async bulkDelete(ids: string[]): Promise<number> {
+ let count = 0;
+ for (const id of ids) {
+ const entry = this.entries.get(id);
+ if (entry) {
+ this.entries.delete(id);
+ this.keyIndex.delete(this.compositeKey(entry.namespace, entry.key));
+ if (this.hnswIndex) this.hnswIndex.remove(id);
+ count++;
+ }
+ }
+ this.dirty = true;
+ return count;
+ }
+
+ async count(namespace?: string): Promise<number> {
+ if (!namespace) return this.entries.size;
+ let c = 0;
+ for (const entry of this.entries.values()) {
+ if (entry.namespace === namespace) c++;
+ }
+ return c;
+ }
+
+ async listNamespaces(): Promise<string[]> {
+ const ns = new Set<string>();
+ for (const entry of this.entries.values()) ns.add(entry.namespace);
+ return Array.from(ns);
+ }
+
+ async clearNamespace(namespace: string): Promise<number> {
+ const toDelete: string[] = [];
+ for (const [id, entry] of this.entries) {
+ if (entry.namespace === namespace) toDelete.push(id);
+ }
+ for (const id of toDelete) {
+ const entry = this.entries.get(id)!;
+ this.entries.delete(id);
+ this.keyIndex.delete(this.compositeKey(entry.namespace, entry.key));
+ if (this.hnswIndex) this.hnswIndex.remove(id);
+ }
+ if (toDelete.length > 0) this.dirty = true;
+ return toDelete.length;
+ }
+
+ async getStats(): Promise<BackendStats> {
+ const entriesByNamespace: Record<string, number> = {};
+ const entriesByType: Record<string, number> = {};
+ let memoryUsage = 0;
+
+ for (const entry of this.entries.values()) {
+ entriesByNamespace[entry.namespace] = (entriesByNamespace[entry.namespace] ?? 0) + 1;
+ entriesByType[entry.type] = (entriesByType[entry.type] ?? 0) + 1;
+ memoryUsage += entry.content.length * 2;
+ if (entry.embedding) memoryUsage += entry.embedding.byteLength;
+ }
+
+ const avgQuery = this.avg(this.queryTimes);
+ const avgSearch = this.avg(this.searchTimes);
+
+ return {
+ totalEntries: this.entries.size,
+ entriesByNamespace,
+ entriesByType: entriesByType as Record<MemoryType, number>,
+ memoryUsage,
+ hnswStats: this.hnswIndex ? {
+ vectorCount: this.hnswIndex.size,
+ memoryUsage: this.hnswIndex.size * this.config.dimensions * 4,
+ avgSearchTime: avgSearch,
+ buildTime: 0,
+ } : undefined,
+ avgQueryTime: avgQuery,
+ avgSearchTime: avgSearch,
+ };
+ }
+
+ async healthCheck(): Promise<HealthCheckResult> {
+ const issues: string[] = [];
+ const recommendations: string[] = [];
+
+ if (!this.initialized) issues.push('Backend not initialized');
+ if (!this.hnswIndex && !this.nativeDb) {
+ issues.push('No vector index available');
+ recommendations.push('Install @ruvector/rvf for native HNSW performance');
+ }
+
+ const status = issues.length === 0
+ ? 'healthy'
+ : issues.some(i => i.includes('not initialized')) ? 'unhealthy' : 'degraded';
+
+ return {
+ status,
+ components: {
+ storage: { status: this.initialized ? 'healthy' : 'unhealthy', latency: 0 },
+ index: { status: this.hnswIndex || this.nativeDb ? 'healthy' : 'degraded', latency: 0 },
+ cache: { status: 'healthy', latency: 0 },
+ },
+ timestamp: Date.now(),
+ issues,
+ recommendations,
+ };
+ }
+
+ private async tryNativeInit(): Promise<boolean> {
+ try {
+ const rvf = await import('@ruvector/rvf' as string);
+ this.nativeDb = new rvf.RvfDatabase({
+ path: this.config.databasePath,
+ dimensions: this.config.dimensions,
+ metric: this.config.metric,
+ quantization: this.config.quantization,
+ hnswM: this.config.hnswM,
+ hnswEfConstruction: this.config.hnswEfConstruction,
+ maxElements: this.config.maxElements,
+ });
+ await this.nativeDb.open();
+ if (this.config.verbose) {
+ console.log('[RvfBackend] Native @ruvector/rvf loaded successfully');
+ }
+ return true;
+ } catch {
+ if (this.config.verbose) {
+ console.log('[RvfBackend] @ruvector/rvf not available, using pure-TS fallback');
+ }
+ return false;
+ }
+ }
+
+ private compositeKey(namespace: string, key: string): string {
+ return `${namespace}\0${key}`;
+ }
+
+ private bruteForceSearch(embedding: Float32Array, options: SearchOptions): SearchResult[] {
+ const results: SearchResult[] = [];
+ for (const entry of this.entries.values()) {
+ if (!entry.embedding) continue;
+ const score = cosineSimilarity(embedding, entry.embedding);
+ if (options.threshold && score < options.threshold) continue;
+ if (options.filters?.namespace && entry.namespace !== options.filters.namespace) continue;
+ if (options.filters?.tags && !options.filters.tags.every(t => entry.tags.includes(t))) continue;
+ results.push({ entry, score, distance: 1 - score });
+ }
+ results.sort((a, b) => b.score - a.score);
+ return results.slice(0, options.k);
+ }
+
+ private recordTiming(arr: number[], start: number): void {
+ arr.push(performance.now() - start);
+ if (arr.length > 100) arr.shift();
+ }
+
+ private avg(arr: number[]): number {
+ return arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+ }
+
+ private async loadFromDisk(): Promise<void> {
+ if (this.config.databasePath === ':memory:') return;
+ if (!existsSync(this.config.databasePath)) return;
+
+ try {
+ const raw = await readFile(this.config.databasePath);
+ if (raw.length < 8) return;
+
+ const magic = String.fromCharCode(raw[0], raw[1], raw[2], raw[3]);
+ if (magic !== MAGIC) return;
+
+ const headerLen = raw.readUInt32LE(4);
+ const MAX_HEADER_SIZE = 10 * 1024 * 1024; // 10MB max header
+ if (headerLen > MAX_HEADER_SIZE || 8 + headerLen > raw.length) return;
+ const headerJson = raw.subarray(8, 8 + headerLen).toString('utf-8');
+ let header: RvfHeader;
+ try {
+ header = JSON.parse(headerJson);
+ } catch {
+ if (this.config.verbose) console.error('[RvfBackend] Corrupt RVF header');
+ return;
+ }
+ if (!header || typeof header.entryCount !== 'number' || typeof header.version !== 'number') return;
+
+ let offset = 8 + headerLen;
+ for (let i = 0; i < header.entryCount; i++) {
+ if (offset + 4 > raw.length) break;
+ const entryLen = raw.readUInt32LE(offset);
+ offset += 4;
+ if (offset + entryLen > raw.length) break;
+
+ const entryJson = raw.subarray(offset, offset + entryLen).toString('utf-8');
+ offset += entryLen;
+
+ const parsed = JSON.parse(entryJson);
+ if (parsed.embedding) parsed.embedding = new Float32Array(parsed.embedding);
+
+ const entry: MemoryEntry = parsed;
+ this.entries.set(entry.id, entry);
+ this.keyIndex.set(this.compositeKey(entry.namespace, entry.key), entry.id);
+ if (entry.embedding && this.hnswIndex) this.hnswIndex.add(entry.id, entry.embedding);
+ }
+ } catch (err) {
+ if (this.config.verbose) {
+ console.error('[RvfBackend] Error loading from disk:', err);
+ }
+ }
+ }
+
+ private async persistToDisk(): Promise<void> {
+ if (this.config.databasePath === ':memory:') return;
+ if (this.persisting) return; // Prevent concurrent persist calls
+ this.persisting = true;
+
+ try {
+ const dir = dirname(this.config.databasePath);
+ if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+
+ const entries = Array.from(this.entries.values());
+
+ // Compute min createdAt without spread operator (avoids stack overflow for large arrays)
+ let minCreatedAt = Date.now();
+ for (const e of entries) {
+ if (e.createdAt < minCreatedAt) minCreatedAt = e.createdAt;
+ }
+
+ const header: RvfHeader = {
+ magic: MAGIC,
+ version: VERSION,
+ dimensions: this.config.dimensions,
+ metric: this.config.metric,
+ quantization: this.config.quantization,
+ entryCount: entries.length,
+ createdAt: entries.length > 0 ? minCreatedAt : Date.now(),
+ updatedAt: Date.now(),
+ };
+
+ const headerBuf = Buffer.from(JSON.stringify(header), 'utf-8');
+ const entryBuffers: Buffer[] = [];
+
+ for (const entry of entries) {
+ const serialized = {
+ ...entry,
+ embedding: entry.embedding ? Array.from(entry.embedding) : undefined,
+ };
+ const buf = Buffer.from(JSON.stringify(serialized), 'utf-8');
+ const lenBuf = Buffer.alloc(4);
+ lenBuf.writeUInt32LE(buf.length, 0);
+ entryBuffers.push(lenBuf, buf);
+ }
+
+ const magicBuf = Buffer.from([0x52, 0x56, 0x46, 0x00]);
+ const headerLenBuf = Buffer.alloc(4);
+ headerLenBuf.writeUInt32LE(headerBuf.length, 0);
+
+ const output = Buffer.concat([magicBuf, headerLenBuf, headerBuf, ...entryBuffers]);
+
+ // Atomic write: write to temp file then rename (crash-safe)
+ const tmpPath = this.config.databasePath + '.tmp';
+ await writeFile(tmpPath, output);
+ await rename(tmpPath, this.config.databasePath);
+ this.dirty = false;
+ } finally {
+ this.persisting = false;
+ }
+ }
+}
diff --git a/v3/@claude-flow/memory/src/rvf-learning-store.ts b/v3/@claude-flow/memory/src/rvf-learning-store.ts
new file mode 100644
index 0000000000..844fb3caf5
--- /dev/null
+++ b/v3/@claude-flow/memory/src/rvf-learning-store.ts
@@ -0,0 +1,410 @@
+/**
+ * RvfLearningStore - Persistent storage for SONA learning artifacts
+ *
+ * Stores patterns, LoRA adapters, EWC state, and trajectories in a
+ * binary-header JSON-lines file format for fast append and rebuild.
+ *
+ * File format:
+ * 4-byte magic "RVLS" + newline
+ * One JSON record per line: {"type":"pattern"|"lora"|"ewc"|"trajectory","data":{...}}
+ *
+ * @module @claude-flow/memory/rvf-learning-store
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ===== Types =====
+
+export interface RvfLearningStoreConfig {
+ /** Path to the persistence file */
+ storePath: string;
+ /** SONA embedding dimension (default: 64) */
+ dimensions?: number;
+ /** Auto-persist interval in ms (default: 30000) */
+ autoPersistInterval?: number;
+ /** Enable verbose logging (default: false) */
+ verbose?: boolean;
+}
+
+export interface PatternRecord {
+ id: string;
+ type: string;
+ embedding: number[];
+ successRate: number;
+ useCount: number;
+ lastUsed: string;
+}
+
+export interface LoraRecord {
+ id: string;
+ config: Record<string, unknown>;
+ weights: string;
+ frozen: boolean;
+ numParameters: number;
+}
+
+export interface EwcRecord {
+ tasksLearned: number;
+ protectionStrength: number;
+ forgettingRate: number;
+ taskWeights: Record<string, number[]>;
+}
+
+export interface TrajectoryRecord {
+ id: string;
+ steps: Array<{
+ type: string;
+ input: string;
+ output: string;
+ durationMs: number;
+ confidence: number;
+ }>;
+ outcome: string;
+ durationMs: number;
+ timestamp: string;
+}
+
+type RecordType = 'pattern' | 'lora' | 'ewc' | 'trajectory';
+
+interface StoreLine {
+ type: RecordType;
+ data: PatternRecord | LoraRecord | EwcRecord | TrajectoryRecord;
+}
+
+// ===== Constants =====
+
+const MAGIC_HEADER = 'RVLS';
+const DEFAULT_DIMENSIONS = 64;
+const DEFAULT_AUTO_PERSIST_MS = 30_000;
+
+// ===== Helpers =====
+
+function ensureDirectory(filePath: string): void {
+ const dir = path.dirname(filePath);
+ if (!fs.existsSync(dir)) {
+ fs.mkdirSync(dir, { recursive: true });
+ }
+}
+
+// ===== RvfLearningStore =====
+
+/**
+ * Persistent store for SONA learning artifacts.
+ *
+ * Maintains in-memory maps for fast reads and flushes to a JSON-lines
+ * file with a binary header on persist(). On initialize(), the file is
+ * read line-by-line to rebuild state.
+ *
+ * @example
+ * ```typescript
+ * const store = new RvfLearningStore({ storePath: './data/learning.rvls' });
+ * await store.initialize();
+ *
+ * await store.savePatterns([{ id: 'p1', type: 'query_response', ... }]);
+ * await store.persist();
+ * await store.close();
+ * ```
+ */
+export class RvfLearningStore {
+ private config: Required<RvfLearningStoreConfig>;
+ private patterns: Map<string, PatternRecord> = new Map();
+ private loraAdapters: Map<string, LoraRecord> = new Map();
+ private ewcState: EwcRecord | null = null;
+ private trajectories: TrajectoryRecord[] = [];
+ private dirty = false;
+ private initialized = false;
+ private autoPersistTimer: ReturnType<typeof setInterval> | null = null;
+
+ constructor(config: RvfLearningStoreConfig) {
+ this.config = {
+ storePath: config.storePath,
+ dimensions: config.dimensions ?? DEFAULT_DIMENSIONS,
+ autoPersistInterval: config.autoPersistInterval ?? DEFAULT_AUTO_PERSIST_MS,
+ verbose: config.verbose ?? false,
+ };
+ }
+
+ /**
+ * Initialize the store by loading any existing data from disk.
+ * Creates the parent directory if it does not exist.
+ */
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ ensureDirectory(this.config.storePath);
+
+ if (fs.existsSync(this.config.storePath)) {
+ await this.loadFromDisk();
+ }
+
+ if (this.config.autoPersistInterval > 0) {
+ this.autoPersistTimer = setInterval(
+ () => void this.persist().catch(() => {}),
+ this.config.autoPersistInterval,
+ );
+ // Allow the process to exit even if the timer is active
+ if (this.autoPersistTimer.unref) {
+ this.autoPersistTimer.unref();
+ }
+ }
+
+ this.initialized = true;
+ this.log('Store initialized');
+ }
+
+ // ===== Pattern operations =====
+
+ /**
+ * Save or update patterns. Existing patterns with matching IDs are
+ * overwritten; new patterns are added.
+ *
+ * @returns The number of patterns stored
+ */
+ async savePatterns(patterns: PatternRecord[]): Promise<number> {
+ this.ensureInitialized();
+ let count = 0;
+ for (const pattern of patterns) {
+ this.patterns.set(pattern.id, { ...pattern });
+ count++;
+ }
+ this.dirty = true;
+ return count;
+ }
+
+ /** Load all patterns currently held in memory */
+ async loadPatterns(): Promise<PatternRecord[]> {
+ this.ensureInitialized();
+ return Array.from(this.patterns.values());
+ }
+
+ /** Return the number of stored patterns */
+ async getPatternCount(): Promise<number> {
+ this.ensureInitialized();
+ return this.patterns.size;
+ }
+
+ // ===== LoRA operations =====
+
+ /** Save or update a LoRA adapter record */
+ async saveLoraAdapter(record: LoraRecord): Promise<void> {
+ this.ensureInitialized();
+ this.loraAdapters.set(record.id, { ...record });
+ this.dirty = true;
+ }
+
+ /** Load all LoRA adapter records */
+ async loadLoraAdapters(): Promise<LoraRecord[]> {
+ this.ensureInitialized();
+ return Array.from(this.loraAdapters.values());
+ }
+
+ /** Delete a LoRA adapter by ID */
+ async deleteLoraAdapter(id: string): Promise<boolean> {
+ this.ensureInitialized();
+ const existed = this.loraAdapters.delete(id);
+ if (existed) this.dirty = true;
+ return existed;
+ }
+
+ // ===== EWC operations =====
+
+ /** Save EWC state (replaces any existing state) */
+ async saveEwcState(record: EwcRecord): Promise<void> {
+ this.ensureInitialized();
+ this.ewcState = { ...record };
+ this.dirty = true;
+ }
+
+ /** Load the EWC state, or null if none has been stored */
+ async loadEwcState(): Promise<EwcRecord | null> {
+ this.ensureInitialized();
+ return this.ewcState ? { ...this.ewcState } : null;
+ }
+
+ // ===== Trajectory operations =====
+
+ /** Append a trajectory record (append-only, never overwritten) */
+ async appendTrajectory(record: TrajectoryRecord): Promise<void> {
+ this.ensureInitialized();
+ this.trajectories.push({ ...record });
+ this.dirty = true;
+ }
+
+ /**
+ * Return stored trajectories, newest first.
+ * @param limit Maximum number to return (default: all)
+ */
+ async getTrajectories(limit?: number): Promise<TrajectoryRecord[]> {
+ this.ensureInitialized();
+ const sorted = [...this.trajectories].reverse();
+ return limit !== undefined ? sorted.slice(0, limit) : sorted;
+ }
+
+ /** Return the number of stored trajectories */
+ async getTrajectoryCount(): Promise<number> {
+ this.ensureInitialized();
+ return this.trajectories.length;
+ }
+
+ // ===== Lifecycle =====
+
+ /**
+ * Flush all in-memory state to disk. The entire file is rewritten
+ * to ensure consistency (patterns may have been updated in-place).
+ */
+ async persist(): Promise<void> {
+ if (!this.dirty) return;
+
+ ensureDirectory(this.config.storePath);
+
+ const lines: string[] = [MAGIC_HEADER];
+
+ // Patterns
+ for (const pattern of this.patterns.values()) {
+ lines.push(JSON.stringify({ type: 'pattern', data: pattern }));
+ }
+
+ // LoRA adapters
+ for (const lora of this.loraAdapters.values()) {
+ lines.push(JSON.stringify({ type: 'lora', data: lora }));
+ }
+
+ // EWC state
+ if (this.ewcState) {
+ lines.push(JSON.stringify({ type: 'ewc', data: this.ewcState }));
+ }
+
+ // Trajectories
+ for (const traj of this.trajectories) {
+ lines.push(JSON.stringify({ type: 'trajectory', data: traj }));
+ }
+
+ const content = lines.join('\n') + '\n';
+ const tmpPath = this.config.storePath + '.tmp';
+
+ await fs.promises.writeFile(tmpPath, content, 'utf-8');
+ await fs.promises.rename(tmpPath, this.config.storePath);
+
+ this.dirty = false;
+ this.log(`Persisted: ${this.patterns.size} patterns, ${this.loraAdapters.size} LoRA, ${this.trajectories.length} trajectories`);
+ }
+
+ /** Persist and release resources */
+ async close(): Promise<void> {
+ if (this.autoPersistTimer) {
+ clearInterval(this.autoPersistTimer);
+ this.autoPersistTimer = null;
+ }
+
+ if (this.dirty) {
+ await this.persist();
+ }
+
+ this.initialized = false;
+ this.log('Store closed');
+ }
+
+ // ===== Stats =====
+
+ /** Return summary statistics about the store */
+ async getStats(): Promise<{
+ patterns: number;
+ loraAdapters: number;
+ trajectories: number;
+ hasEwcState: boolean;
+ fileSizeBytes: number;
+ }> {
+ this.ensureInitialized();
+
+ let fileSizeBytes = 0;
+ try {
+ const stat = await fs.promises.stat(this.config.storePath);
+ fileSizeBytes = stat.size;
+ } catch {
+ // File may not exist yet if nothing has been persisted
+ }
+
+ return {
+ patterns: this.patterns.size,
+ loraAdapters: this.loraAdapters.size,
+ trajectories: this.trajectories.length,
+ hasEwcState: this.ewcState !== null,
+ fileSizeBytes,
+ };
+ }
+
+ // ===== Private =====
+
+ private async loadFromDisk(): Promise<void> {
+ let content: string;
+ try {
+ content = await fs.promises.readFile(this.config.storePath, 'utf-8');
+ } catch {
+ return;
+ }
+
+ const lines = content.split('\n').filter((l) => l.trim().length > 0);
+ if (lines.length === 0) return;
+
+ // Verify magic header
+ if (lines[0] !== MAGIC_HEADER) {
+ this.log(`Warning: invalid magic header "${lines[0]}", expected "${MAGIC_HEADER}"`);
+ return;
+ }
+
+ let parsed = 0;
+ let errors = 0;
+
+ for (let i = 1; i < lines.length; i++) {
+ try {
+ const record = JSON.parse(lines[i]) as StoreLine;
+ this.applyRecord(record);
+ parsed++;
+ } catch {
+ errors++;
+ this.log(`Warning: failed to parse line ${i + 1}`);
+ }
+ }
+
+ this.log(`Loaded from disk: ${parsed} records, ${errors} errors`);
+ }
+
+ private applyRecord(record: StoreLine): void {
+ switch (record.type) {
+ case 'pattern': {
+ const p = record.data as PatternRecord;
+ this.patterns.set(p.id, p);
+ break;
+ }
+ case 'lora': {
+ const l = record.data as LoraRecord;
+ this.loraAdapters.set(l.id, l);
+ break;
+ }
+ case 'ewc': {
+ this.ewcState = record.data as EwcRecord;
+ break;
+ }
+ case 'trajectory': {
+ this.trajectories.push(record.data as TrajectoryRecord);
+ break;
+ }
+ default:
+ this.log(`Warning: unknown record type "${record.type}"`);
+ }
+ }
+
+ private ensureInitialized(): void {
+ if (!this.initialized) {
+ throw new Error('RvfLearningStore has not been initialized. Call initialize() first.');
+ }
+ }
+
+ private log(message: string): void {
+ if (this.config.verbose) {
+ // eslint-disable-next-line no-console
+ console.log(`[RvfLearningStore] ${message}`);
+ }
+ }
+}
diff --git a/v3/@claude-flow/memory/src/rvf-migration.ts b/v3/@claude-flow/memory/src/rvf-migration.ts
new file mode 100644
index 0000000000..2858aa5919
--- /dev/null
+++ b/v3/@claude-flow/memory/src/rvf-migration.ts
@@ -0,0 +1,254 @@
+/**
+ * RVF Migration Utility β€” bidirectional migration between RVF and legacy
+ * formats (JSON files, sql.js / better-sqlite3 databases).
+ * @module @claude-flow/memory/rvf-migration
+ */
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { RvfBackend } from './rvf-backend.js';
+import type { MemoryEntry, MemoryType, AccessLevel } from './types.js';
+import { generateMemoryId } from './types.js';
+
+/** Options for controlling the migration process. */
+export interface RvfMigrationOptions {
+ verbose?: boolean;
+ /** Entries per batch (default 500). */
+ batchSize?: number;
+ /** Embedding dimensions for target RVF file (default 1536). */
+ dimensions?: number;
+ onProgress?: (progress: { current: number; total: number; phase: string }) => void;
+}
+
+/** Result returned after a migration completes. */
+export interface RvfMigrationResult {
+ success: boolean;
+ entriesMigrated: number;
+ sourceFormat: string;
+ targetFormat: string;
+ durationMs: number;
+ errors: string[];
+}
+
+// -- Internal helpers -------------------------------------------------------
+
+function fillDefaults(raw: Record<string, unknown>): MemoryEntry {
+ const now = Date.now();
+ return {
+ id: (raw.id as string) ?? generateMemoryId(),
+ key: (raw.key as string) ?? '',
+ content: (raw.content as string) ?? '',
+ type: (raw.type as MemoryType) ?? 'semantic',
+ namespace: (raw.namespace as string) ?? 'default',
+ tags: (raw.tags as string[]) ?? [],
+ metadata: (raw.metadata as Record<string, unknown>) ?? {},
+ ownerId: raw.ownerId as string | undefined,
+ accessLevel: (raw.accessLevel as AccessLevel) ?? 'private',
+ createdAt: (raw.createdAt as number) ?? now,
+ updatedAt: (raw.updatedAt as number) ?? now,
+ expiresAt: raw.expiresAt as number | undefined,
+ version: (raw.version as number) ?? 1,
+ references: (raw.references as string[]) ?? [],
+ accessCount: (raw.accessCount as number) ?? 0,
+ lastAccessedAt: (raw.lastAccessedAt as number) ?? now,
+ embedding: deserializeEmbedding(raw.embedding),
+ };
+}
+
+function deserializeEmbedding(value: unknown): Float32Array | undefined {
+ if (!value) return undefined;
+ if (value instanceof Float32Array) return value;
+ if (value instanceof Buffer || value instanceof Uint8Array) {
+ if (value.byteLength === 0) return undefined;
+ const out = new Float32Array(value.byteLength / 4);
+ const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+ for (let i = 0; i < out.length; i++) out[i] = view.getFloat32(i * 4, true);
+ return out;
+ }
+ if (Array.isArray(value)) return new Float32Array(value as number[]);
+ return undefined;
+}
+
+function serializeForJson(entry: MemoryEntry): Record<string, unknown> {
+ return { ...entry, embedding: entry.embedding ? Array.from(entry.embedding) : undefined };
+}
+
+function validateMigrationPath(p: string): void {
+ if (!p || typeof p !== 'string') throw new Error('Path must be a non-empty string');
+ if (p.includes('\0')) throw new Error('Path contains null bytes');
+}
+
+async function ensureDir(filePath: string): Promise<void> {
+ validateMigrationPath(filePath);
+ const dir = dirname(resolve(filePath));
+ if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+}
+
+async function atomicWrite(targetPath: string, data: string | Buffer): Promise<void> {
+ validateMigrationPath(targetPath);
+ const abs = resolve(targetPath);
+ const tmp = abs + '.tmp.' + Date.now();
+ await ensureDir(abs);
+ await writeFile(tmp, data, typeof data === 'string' ? 'utf-8' : undefined);
+ await rename(tmp, abs);
+}
+
+function mkResult(
+ success: boolean, entriesMigrated: number, sourceFormat: string,
+ targetFormat: string, startMs: number, errors: string[],
+): RvfMigrationResult {
+ return { success, entriesMigrated, sourceFormat, targetFormat, durationMs: Date.now() - startMs, errors };
+}
+
+function normalizeSqliteRow(row: Record<string, unknown>): Record<string, unknown> {
+ const out: Record<string, unknown> = { ...row };
+ for (const col of ['tags', 'metadata', 'references'] as const) {
+ if (typeof out[col] === 'string') {
+ try { out[col] = JSON.parse(out[col] as string); } catch { out[col] = col === 'metadata' ? {} : []; }
+ }
+ }
+ return out;
+}
+
+// -- SQLite reader (better-sqlite3 first, then sql.js) ----------------------
+
+interface SqliteRow { [key: string]: unknown }
+
+async function readSqliteRows(dbPath: string): Promise<SqliteRow[]> {
+ // Attempt better-sqlite3
+ try {
+ const mod = await import('better-sqlite3' as string);
+ const Database = mod.default ?? mod;
+ const db = new Database(dbPath, { readonly: true });
+ try { return db.prepare('SELECT * FROM memory_entries').all() as SqliteRow[]; }
+ finally { db.close(); }
+ } catch { /* unavailable */ }
+ // Attempt sql.js
+ try {
+ const mod = await import('sql.js' as string);
+ const SQL = await (mod.default ?? mod)();
+ const db = new SQL.Database(await readFile(dbPath));
+ try {
+ const stmt = db.prepare('SELECT * FROM memory_entries');
+ const rows: SqliteRow[] = [];
+ while (stmt.step()) rows.push(stmt.getAsObject() as SqliteRow);
+ stmt.free();
+ return rows;
+ } finally { db.close(); }
+ } catch { /* unavailable */ }
+ throw new Error('Cannot read SQLite: install better-sqlite3 or sql.js');
+}
+
+// -- Batch migration helper -------------------------------------------------
+
+async function migrateBatches(
+ items: Record<string, unknown>[],
+ rvfPath: string,
+ options: RvfMigrationOptions,
+ normalize?: (r: Record<string, unknown>) => Record<string, unknown>,
+): Promise<{ migrated: number; errors: string[] }> {
+ const batchSize = options.batchSize ?? 500;
+ const dimensions = options.dimensions ?? 1536;
+ const backend = new RvfBackend({ databasePath: rvfPath, dimensions, verbose: options.verbose });
+ await backend.initialize();
+ let migrated = 0;
+ const errors: string[] = [];
+ try {
+ for (let i = 0; i < items.length; i += batchSize) {
+ const batch = items.slice(i, i + batchSize);
+ const entries: MemoryEntry[] = [];
+ for (const item of batch) {
+ try {
+ entries.push(fillDefaults(normalize ? normalize(item) : item));
+ } catch (e) { errors.push(`Entry ${item.id ?? i}: ${(e as Error).message}`); }
+ }
+ if (entries.length > 0) { await backend.bulkInsert(entries); migrated += entries.length; }
+ options.onProgress?.({ current: Math.min(i + batchSize, items.length), total: items.length, phase: 'migrating' });
+ }
+ } finally { await backend.shutdown(); }
+ return { migrated, errors };
+}
+
+/**
+ * Bidirectional migration utility between RVF and legacy memory formats.
+ *
+ * All methods are static β€” no instantiation required.
+ */
+export class RvfMigrator {
+ /** Migrate a JSON memory file to RVF format. */
+ static async fromJsonFile(
+ jsonPath: string, rvfPath: string, options: RvfMigrationOptions = {},
+ ): Promise<RvfMigrationResult> {
+ const start = Date.now();
+ const raw = await readFile(jsonPath, 'utf-8');
+ let parsed: unknown;
+ try { parsed = JSON.parse(raw); }
+ catch (e) { return mkResult(false, 0, 'json', 'rvf', start, [`Invalid JSON: ${(e as Error).message}`]); }
+ const items = Array.isArray(parsed) ? parsed : [parsed as Record<string, unknown>];
+ const { migrated, errors } = await migrateBatches(items, rvfPath, options);
+ if (options.verbose) console.log(`[RvfMigrator] Migrated ${migrated} entries from JSON to RVF`);
+ return mkResult(errors.length === 0, migrated, 'json', 'rvf', start, errors);
+ }
+
+ /** Migrate a SQLite (better-sqlite3 / sql.js) database to RVF. */
+ static async fromSqlite(
+ dbPath: string, rvfPath: string, options: RvfMigrationOptions = {},
+ ): Promise<RvfMigrationResult> {
+ const start = Date.now();
+ let rows: SqliteRow[];
+ try { rows = await readSqliteRows(dbPath); }
+ catch (e) { return mkResult(false, 0, 'sqlite', 'rvf', start, [(e as Error).message]); }
+ options.onProgress?.({ current: 0, total: rows.length, phase: 'reading' });
+ const { migrated, errors } = await migrateBatches(rows, rvfPath, options, normalizeSqliteRow);
+ if (options.verbose) console.log(`[RvfMigrator] Migrated ${migrated} entries from SQLite to RVF`);
+ return mkResult(errors.length === 0, migrated, 'sqlite', 'rvf', start, errors);
+ }
+
+ /** Export an RVF file back to a JSON array (backward compatibility). */
+ static async toJsonFile(rvfPath: string, jsonPath: string): Promise<RvfMigrationResult> {
+ const start = Date.now();
+ const backend = new RvfBackend({ databasePath: rvfPath });
+ await backend.initialize();
+ let entries: MemoryEntry[];
+ try { entries = await backend.query({ type: 'hybrid', limit: Number.MAX_SAFE_INTEGER }); }
+ finally { await backend.shutdown(); }
+ const warnings: string[] = [];
+ if (entries.length === 0) warnings.push('Source RVF file contained no entries');
+ await atomicWrite(jsonPath, JSON.stringify(entries.map(serializeForJson), null, 2));
+ return mkResult(true, entries.length, 'rvf', 'json', start, warnings);
+ }
+
+ /**
+ * Detect file format by magic bytes.
+ * - RVF\0 (0x52 0x56 0x46 0x00) -> 'rvf'
+ * - SQLi (0x53 0x51 0x4C 0x69) -> 'sqlite'
+ * - Leading [ or { -> 'json'
+ */
+ static async detectFormat(filePath: string): Promise<'rvf' | 'json' | 'sqlite' | 'unknown'> {
+ if (!existsSync(filePath)) return 'unknown';
+ const fd = await import('node:fs').then(m => m.promises.open(filePath, 'r'));
+ try {
+ const buf = Buffer.alloc(16);
+ await fd.read(buf, 0, 16, 0);
+ if (buf[0] === 0x52 && buf[1] === 0x56 && buf[2] === 0x46 && buf[3] === 0x00) return 'rvf';
+ if (buf[0] === 0x53 && buf[1] === 0x51 && buf[2] === 0x4C && buf[3] === 0x69) return 'sqlite';
+ const head = buf.toString('utf-8').trimStart();
+ if (head.startsWith('[') || head.startsWith('{')) return 'json';
+ return 'unknown';
+ } finally { await fd.close(); }
+ }
+
+ /** Auto-detect source format and migrate to RVF. */
+ static async autoMigrate(
+ sourcePath: string, targetRvfPath: string, options: RvfMigrationOptions = {},
+ ): Promise<RvfMigrationResult> {
+ const format = await RvfMigrator.detectFormat(sourcePath);
+ if (options.verbose) console.log(`[RvfMigrator] Detected source format: ${format}`);
+ switch (format) {
+ case 'json': return RvfMigrator.fromJsonFile(sourcePath, targetRvfPath, options);
+ case 'sqlite': return RvfMigrator.fromSqlite(sourcePath, targetRvfPath, options);
+ case 'rvf': return { success: true, entriesMigrated: 0, sourceFormat: 'rvf', targetFormat: 'rvf', durationMs: 0, errors: [] };
+ default: return { success: false, entriesMigrated: 0, sourceFormat: 'unknown', targetFormat: 'rvf', durationMs: 0, errors: [`Unrecognized format: ${sourcePath}`] };
+ }
+ }
+}
diff --git a/v3/@claude-flow/shared/src/events/index.ts b/v3/@claude-flow/shared/src/events/index.ts
index eae412f364..8a2a2cd03c 100644
--- a/v3/@claude-flow/shared/src/events/index.ts
+++ b/v3/@claude-flow/shared/src/events/index.ts
@@ -79,6 +79,10 @@ export type {
MemoryProjectionState,
} from './projections.js';
+// RVF Event Log (ADR-057 β€” zero-dependency alternative to EventStore)
+export { RvfEventLog } from './rvf-event-log.js';
+export type { RvfEventLogConfig } from './rvf-event-log.js';
+
// State Reconstruction (ADR-007)
export {
StateReconstructor,
diff --git a/v3/@claude-flow/shared/src/events/rvf-event-log.ts b/v3/@claude-flow/shared/src/events/rvf-event-log.ts
new file mode 100644
index 0000000000..2ca3b708e2
--- /dev/null
+++ b/v3/@claude-flow/shared/src/events/rvf-event-log.ts
@@ -0,0 +1,427 @@
+/**
+ * RVF Event Log (ADR-057 Phase 2)
+ *
+ * Pure-TypeScript append-only event log that stores events in a binary
+ * file format. Replaces the sql.js-dependent EventStore with a zero-
+ * dependency alternative.
+ *
+ * Binary format:
+ * File header: 4 bytes β€” magic "RVFL"
+ * Record: 4 bytes (uint32 BE payload length) + N bytes (JSON payload)
+ *
+ * In-memory indexes are rebuilt on initialize() by replaying the file.
+ * Snapshots are stored in a separate `.snap.rvf` file using the same format.
+ *
+ * @module v3/shared/events/rvf-event-log
+ */
+
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { DomainEvent } from './domain-events.js';
+
+// Re-export shared interfaces so consumers do not need to import event-store.ts
+import type { EventFilter, EventSnapshot, EventStoreStats } from './event-store.js';
+
+/** Validate a file path is safe */
+function validatePath(p: string): void {
+ if (p.includes('\0')) throw new Error('Event log path contains null bytes');
+}
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface RvfEventLogConfig {
+ /** Path to event log file */
+ logPath: string;
+ /** Enable verbose logging */
+ verbose?: boolean;
+ /** Maximum events before snapshot recommendation */
+ snapshotThreshold?: number;
+}
+
+const DEFAULT_CONFIG: Required<RvfEventLogConfig> = {
+ logPath: 'events.rvf',
+ verbose: false,
+ snapshotThreshold: 100,
+};
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Magic bytes that identify an RVF event log file */
+const MAGIC = Buffer.from('RVFL');
+const MAGIC_LENGTH = 4;
+const LENGTH_PREFIX_BYTES = 4;
+
+// =============================================================================
+// RvfEventLog Implementation
+// =============================================================================
+
+export class RvfEventLog extends EventEmitter {
+ private config: Required<RvfEventLogConfig>;
+ private initialized = false;
+
+ /**
+ * All events kept in insertion order.
+ * Rebuilt from the file on initialize().
+ */
+ private events: DomainEvent[] = [];
+
+ /** Fast lookup: aggregateId -> indices into this.events */
+ private aggregateIndex: Map<string, number[]> = new Map();
+
+ /** Version tracking per aggregate */
+ private aggregateVersions: Map<string, number> = new Map();
+
+ /** Snapshots keyed by aggregateId (latest wins) */
+ private snapshots: Map<string, EventSnapshot> = new Map();
+
+ /** Path to the companion snapshot file */
+ private snapshotPath: string;
+
+ constructor(config: Partial<RvfEventLogConfig> = {}) {
+ super();
+ this.config = { ...DEFAULT_CONFIG, ...config } as Required<RvfEventLogConfig>;
+ this.snapshotPath = this.config.logPath.replace(/\.rvf$/, '.snap.rvf');
+ if (this.snapshotPath === this.config.logPath) {
+ this.snapshotPath = this.config.logPath + '.snap.rvf';
+ }
+ validatePath(this.config.logPath);
+ }
+
+ // ===========================================================================
+ // Lifecycle
+ // ===========================================================================
+
+ /** Create / open the log file and rebuild in-memory indexes. */
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ this.ensureDirectory(this.config.logPath);
+
+ // --- events file ---
+ if (existsSync(this.config.logPath)) {
+ this.replayFile(this.config.logPath, (event: DomainEvent) => {
+ this.indexEvent(event);
+ });
+ } else {
+ const tmpLog = this.config.logPath + '.tmp';
+ writeFileSync(tmpLog, MAGIC);
+ renameSync(tmpLog, this.config.logPath);
+ }
+
+ // --- snapshots file ---
+ if (existsSync(this.snapshotPath)) {
+ this.replayFile(this.snapshotPath, (_raw: unknown) => {
+ const snap = _raw as EventSnapshot;
+ this.snapshots.set(snap.aggregateId, snap);
+ });
+ } else {
+ const tmpSnap = this.snapshotPath + '.tmp';
+ writeFileSync(tmpSnap, MAGIC);
+ renameSync(tmpSnap, this.snapshotPath);
+ }
+
+ this.initialized = true;
+
+ if (this.config.verbose) {
+ console.log(
+ `[RvfEventLog] Initialized – ${this.events.length} events, ` +
+ `${this.snapshots.size} snapshots`
+ );
+ }
+
+ this.emit('initialized');
+ }
+
+ /** Flush to disk and release resources. */
+ async close(): Promise<void> {
+ if (!this.initialized) return;
+
+ // All data is already on disk (append-only), so just clear memory.
+ this.events = [];
+ this.aggregateIndex.clear();
+ this.aggregateVersions.clear();
+ this.snapshots.clear();
+ this.initialized = false;
+
+ this.emit('shutdown');
+ }
+
+ // ===========================================================================
+ // Write Operations
+ // ===========================================================================
+
+ /** Append a domain event to the log. */
+ async append(event: DomainEvent): Promise<void> {
+ this.ensureInitialized();
+
+ if (!event.aggregateId || typeof event.aggregateId !== 'string') {
+ throw new Error('Event must have a valid aggregateId string');
+ }
+ if (!event.type || typeof event.type !== 'string') {
+ throw new Error('Event must have a valid type string');
+ }
+
+ // Assign next version for aggregate
+ const currentVersion = this.aggregateVersions.get(event.aggregateId) ?? 0;
+ const nextVersion = currentVersion + 1;
+ event.version = nextVersion;
+
+ // Persist to disk first (crash-safe ordering)
+ this.appendRecord(this.config.logPath, event);
+
+ // Update in-memory state
+ this.indexEvent(event);
+
+ this.emit('event:appended', event);
+
+ if (nextVersion % this.config.snapshotThreshold === 0) {
+ this.emit('snapshot:recommended', {
+ aggregateId: event.aggregateId,
+ version: nextVersion,
+ });
+ }
+ }
+
+ /** Save a snapshot for an aggregate. */
+ async saveSnapshot(snapshot: EventSnapshot): Promise<void> {
+ this.ensureInitialized();
+
+ this.appendRecord(this.snapshotPath, snapshot);
+ this.snapshots.set(snapshot.aggregateId, snapshot);
+
+ this.emit('snapshot:saved', snapshot);
+ }
+
+ // ===========================================================================
+ // Read Operations
+ // ===========================================================================
+
+ /** Get events for a specific aggregate, optionally from a version. */
+ async getEvents(aggregateId: string, fromVersion?: number): Promise<DomainEvent[]> {
+ this.ensureInitialized();
+
+ const indices = this.aggregateIndex.get(aggregateId);
+ if (!indices || indices.length === 0) return [];
+
+ let result = indices.map((i) => this.events[i]);
+
+ if (fromVersion !== undefined) {
+ result = result.filter((e) => e.version >= fromVersion);
+ }
+
+ // Events within an aggregate are already version-ordered because we
+ // append in order, but sort defensively.
+ return result.sort((a, b) => a.version - b.version);
+ }
+
+ /** Query events with an optional filter (matches EventStore.query API). */
+ async getAllEvents(filter?: EventFilter): Promise<DomainEvent[]> {
+ this.ensureInitialized();
+
+ if (!filter) {
+ return [...this.events].sort((a, b) => a.timestamp - b.timestamp);
+ }
+
+ let result: DomainEvent[] = [...this.events];
+
+ // Aggregate ID filter
+ if (filter.aggregateIds && filter.aggregateIds.length > 0) {
+ const set = new Set(filter.aggregateIds);
+ result = result.filter((e) => set.has(e.aggregateId));
+ }
+
+ // Aggregate type filter
+ if (filter.aggregateTypes && filter.aggregateTypes.length > 0) {
+ const set = new Set<string>(filter.aggregateTypes);
+ result = result.filter((e) => set.has(e.aggregateType));
+ }
+
+ // Event type filter
+ if (filter.eventTypes && filter.eventTypes.length > 0) {
+ const set = new Set(filter.eventTypes);
+ result = result.filter((e) => set.has(e.type));
+ }
+
+ // Timestamp filters
+ if (filter.afterTimestamp !== undefined) {
+ result = result.filter((e) => e.timestamp > filter.afterTimestamp!);
+ }
+ if (filter.beforeTimestamp !== undefined) {
+ result = result.filter((e) => e.timestamp < filter.beforeTimestamp!);
+ }
+
+ // Version filter
+ if (filter.fromVersion !== undefined) {
+ result = result.filter((e) => e.version >= filter.fromVersion!);
+ }
+
+ // Sort by timestamp ascending (matches EventStore behaviour)
+ result.sort((a, b) => a.timestamp - b.timestamp);
+
+ // Pagination
+ if (filter.offset) {
+ result = result.slice(filter.offset);
+ }
+ if (filter.limit) {
+ result = result.slice(0, filter.limit);
+ }
+
+ return result;
+ }
+
+ /** Get latest snapshot for an aggregate. */
+ async getSnapshot(aggregateId: string): Promise<EventSnapshot | null> {
+ this.ensureInitialized();
+ return this.snapshots.get(aggregateId) ?? null;
+ }
+
+ /** Return event store statistics. */
+ async getStats(): Promise<EventStoreStats> {
+ this.ensureInitialized();
+
+ const eventsByType: Record<string, number> = {};
+ const eventsByAggregate: Record<string, number> = {};
+ let oldest: number | null = null;
+ let newest: number | null = null;
+
+ for (const event of this.events) {
+ // by type
+ eventsByType[event.type] = (eventsByType[event.type] ?? 0) + 1;
+
+ // by aggregate
+ eventsByAggregate[event.aggregateId] =
+ (eventsByAggregate[event.aggregateId] ?? 0) + 1;
+
+ // timestamp range
+ if (oldest === null || event.timestamp < oldest) oldest = event.timestamp;
+ if (newest === null || event.timestamp > newest) newest = event.timestamp;
+ }
+
+ return {
+ totalEvents: this.events.length,
+ eventsByType,
+ eventsByAggregate,
+ oldestEvent: oldest,
+ newestEvent: newest,
+ snapshotCount: this.snapshots.size,
+ };
+ }
+
+ /**
+ * Flush to disk.
+ * For the append-only log this is a no-op because every append() call
+ * writes to disk synchronously. Provided for API compatibility with
+ * EventStore.
+ */
+ async persist(): Promise<void> {
+ // All records are already flushed on append. Nothing to do.
+ if (this.config.verbose) {
+ console.log('[RvfEventLog] persist() called β€” all data already on disk');
+ }
+ }
+
+ // ===========================================================================
+ // Private Helpers
+ // ===========================================================================
+
+ /**
+ * Replay an RVF file and invoke `handler` for every decoded record.
+ * Used both for events and snapshots.
+ */
+ private replayFile(filePath: string, handler: (record: any) => void): void {
+ const buf = readFileSync(filePath);
+
+ // Validate magic
+ if (buf.length < MAGIC_LENGTH || buf.subarray(0, MAGIC_LENGTH).compare(MAGIC) !== 0) {
+ throw new Error(`[RvfEventLog] Invalid file header in ${filePath}`);
+ }
+
+ let offset = MAGIC_LENGTH;
+
+ const MAX_PAYLOAD_SIZE = 100 * 1024 * 1024; // 100MB safety limit
+ while (offset + LENGTH_PREFIX_BYTES <= buf.length) {
+ const payloadLength = buf.readUInt32BE(offset);
+ offset += LENGTH_PREFIX_BYTES;
+
+ if (payloadLength > MAX_PAYLOAD_SIZE) {
+ if (this.config.verbose) {
+ console.warn(`[RvfEventLog] Payload size ${payloadLength} exceeds safety limit`);
+ }
+ break;
+ }
+
+ if (offset + payloadLength > buf.length) {
+ // Truncated record β€” stop reading (crash recovery).
+ if (this.config.verbose) {
+ console.warn(
+ `[RvfEventLog] Truncated record at offset ${offset - LENGTH_PREFIX_BYTES} β€” ` +
+ `expected ${payloadLength} bytes, have ${buf.length - offset}`
+ );
+ }
+ break;
+ }
+
+ const json = buf.subarray(offset, offset + payloadLength).toString('utf8');
+ offset += payloadLength;
+
+ try {
+ const record = JSON.parse(json);
+ handler(record);
+ } catch {
+ if (this.config.verbose) {
+ console.warn(`[RvfEventLog] Corrupt JSON record skipped`);
+ }
+ }
+ }
+ }
+
+ /** Append a single record to an RVF file. */
+ private appendRecord(filePath: string, record: unknown): void {
+ const json = JSON.stringify(record);
+ const payload = Buffer.from(json, 'utf8');
+ const lengthBuf = Buffer.allocUnsafe(LENGTH_PREFIX_BYTES);
+ lengthBuf.writeUInt32BE(payload.length, 0);
+
+ appendFileSync(filePath, Buffer.concat([lengthBuf, payload]));
+ }
+
+ /** Add an event to the in-memory indexes. */
+ private indexEvent(event: DomainEvent): void {
+ const idx = this.events.length;
+ this.events.push(event);
+
+ // aggregateIndex
+ let indices = this.aggregateIndex.get(event.aggregateId);
+ if (!indices) {
+ indices = [];
+ this.aggregateIndex.set(event.aggregateId, indices);
+ }
+ indices.push(idx);
+
+ // version tracker
+ const current = this.aggregateVersions.get(event.aggregateId) ?? 0;
+ if (event.version > current) {
+ this.aggregateVersions.set(event.aggregateId, event.version);
+ }
+ }
+
+ /** Ensure parent directory exists for a file path. */
+ private ensureDirectory(filePath: string): void {
+ const dir = dirname(filePath);
+ if (!existsSync(dir)) {
+ mkdirSync(dir, { recursive: true });
+ }
+ }
+
+ /** Guard that throws if initialize() has not been called. */
+ private ensureInitialized(): void {
+ if (!this.initialized) {
+ throw new Error('RvfEventLog not initialized. Call initialize() first.');
+ }
+ }
+}
diff --git a/v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md b/v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md
new file mode 100644
index 0000000000..fa3007b507
--- /dev/null
+++ b/v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md
@@ -0,0 +1,1512 @@
+# ADR-057: RVF Native Storage Backend β€” Replace sql.js with RuVector Format
+
+| Field | Value |
+|-------|-------|
+| **Status** | Proposed |
+| **Date** | 2026-02-28 |
+| **Authors** | Claude Flow Team |
+| **Supersedes** | β€” |
+| **Related** | ADR-053 (AgentDB Controller Activation), ADR-054 (RVF Plugin Marketplace), ADR-055 (Controller Bug Remediation), ADR-056 (agentic-flow v3 Integration) |
+
+---
+
+## 1. Context
+
+### The Problem
+
+`npx ruflo@latest` installs **1.3GB** across 914 packages with a 35-second cold start in Docker. The Docker optimization work (Dockerfile.lite with `--omit=optional` + aggressive pruning) reduced this to 324MB, but the **core dependency chain** still carries unnecessary weight:
+
+```
+ruflo (5KB wrapper)
+ └─ @claude-flow/cli (9MB)
+ β”œβ”€ @claude-flow/shared (11MB) ← depends on sql.js (18MB WASM)
+ β”œβ”€ @claude-flow/mcp (650KB)
+ β”œβ”€ semver (tiny)
+ └─ @noble/ed25519 (tiny)
+```
+
+**`sql.js` is the single largest hard dependency** β€” an 18MB WASM SQLite bundle compiled from C via Emscripten. It is used in three places:
+
+| Consumer | File | Purpose | Lines |
+|----------|------|---------|-------|
+| `@claude-flow/shared` | `events/event-store.ts` | Append-only event sourcing log | 589 |
+| `@claude-flow/memory` | `sqljs-backend.ts` | Memory entries + brute-force vector search | 767 |
+| `@claude-flow/embeddings` | `persistent-cache.ts` | LRU embedding cache with TTL | 411 |
+
+### What sql.js Actually Does
+
+Analysis of all 1,767 lines of sql.js-consuming code reveals:
+
+1. **Key-value storage** with namespace isolation
+2. **BLOB columns** for Float32Array embedding vectors
+3. **JSON TEXT columns** for metadata, tags, references
+4. **Dynamic SQL filtering** (namespace, type, time range, pagination)
+5. **Append-only event log** with version tracking and snapshots
+6. **LRU cache** with TTL-based eviction
+7. **Brute-force cosine similarity** search (no indexing)
+
+Notably, sql.js provides **no vector indexing** β€” the SqlJsBackend comments explicitly state:
+
+```typescript
+// sql.js doesn't have native vector index
+message: 'No vector index (brute-force search)',
+recommendations.push('Consider using better-sqlite3 with HNSW for faster vector search');
+```
+
+### The Opportunity
+
+RVF (RuVector Format) is a binary container format already used in the Claude Flow ecosystem (ADR-054). It provides everything sql.js does **plus native HNSW indexing** in a fraction of the footprint:
+
+| Capability | sql.js | RVF |
+|-----------|--------|-----|
+| Package size | 18MB WASM | ~50 bytes/vector overhead |
+| Vector search | Brute-force O(n) | HNSW 3-layer progressive (150x-12,500x faster) |
+| Quantization | None | fp16, fp32, int8, int4, binary |
+| Crash safety | Manual export/save | Append-only (no WAL needed) |
+| COW branching | N/A | <3ms branch, 1:200 compression |
+| WASM support | 18MB Emscripten bundle | 5.5KB microkernel + 46KB control plane |
+| Native support | N/A | NAPI-RS (zero-copy) |
+| Key-value store | SQL tables | MANIFEST + KV_SEG segments |
+| Event log | SQL INSERT | Append-only LOG_SEG |
+| Cross-platform | Yes (WASM-only) | Yes (native + WASM fallback) |
+
+---
+
+## 2. Decision
+
+**Replace sql.js with RVF as the native storage backend** across `@claude-flow/shared`, `@claude-flow/memory`, and `@claude-flow/embeddings`. Provide automatic and manual migration paths for existing SQLite (`.db`) and JSON (`.json`) data files with full backward compatibility.
+
+### Storage Architecture
+
+```
+Before (sql.js):
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ @claude-flow/shared β”‚
+β”‚ β”œβ”€ EventStore β†’ sql.js (18MB WASM) β”‚
+β”‚ └─ event-store.db β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ @claude-flow/memory β”‚
+β”‚ β”œβ”€ SqlJsBackend β†’ sql.js β”‚
+β”‚ └─ memory.db β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ @claude-flow/embeddings β”‚
+β”‚ β”œβ”€ PersistentCache β†’ sql.js β”‚
+β”‚ └─ embeddings.db β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+
+After (RVF):
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ @claude-flow/shared β”‚
+β”‚ β”œβ”€ EventStore β†’ RvfEventLog β”‚
+β”‚ └─ events.rvf (LOG_SEG) β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ @claude-flow/memory β”‚
+β”‚ β”œβ”€ RvfBackend β†’ RVF native β”‚
+β”‚ └─ memory.rvf (VEC_SEG + KV_SEG) β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ @claude-flow/embeddings β”‚
+β”‚ β”œβ”€ RvfEmbeddingCache β†’ RVF native β”‚
+β”‚ └─ embeddings.rvf (VEC_SEG) β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+### Segment Mapping
+
+| sql.js Table | RVF Segment | Purpose |
+|-------------|-------------|---------|
+| `memory_entries` | `KV_SEG` + `VEC_SEG` | Key-value metadata + vector embeddings |
+| `memory_entries.embedding` (BLOB) | `VEC_SEG` (fp32/fp16/int8) | Typed vector storage with quantization |
+| `events` | `LOG_SEG` | Append-only event log (replaces SQL INSERT) |
+| `snapshots` | `SNAP_SEG` | Event sourcing snapshots |
+| `embeddings` | `VEC_SEG` + `INDEX_SEG` | Cached embeddings with HNSW index |
+| Dynamic SQL indexes | `INDEX_SEG` (3-layer HNSW) | Progressive loading: 70% recall on first query |
+| JSON metadata columns | `META_SEG` | Structured metadata without JSON.parse overhead |
+
+---
+
+## 3. Migration Strategy
+
+### 3.1 File Detection and Format Routing
+
+The system detects the storage format by file extension and magic bytes:
+
+```typescript
+enum StorageFormat {
+ SQLITE_SQLJS = 'sqlite-sqljs', // .db files from sql.js
+ SQLITE_NATIVE = 'sqlite-native', // .db files from better-sqlite3
+ JSON = 'json', // .json fallback files
+ RVF = 'rvf', // .rvf native format
+ UNKNOWN = 'unknown',
+}
+
+function detectFormat(filePath: string): StorageFormat {
+ if (!existsSync(filePath)) return StorageFormat.UNKNOWN;
+
+ const ext = extname(filePath).toLowerCase();
+ const header = readFileSync(filePath, { length: 16 });
+
+ // RVF magic bytes: first 4 bytes
+ if (header.slice(0, 4).toString() === 'RVF\0') return StorageFormat.RVF;
+
+ // SQLite magic: "SQLite format 3\0"
+ if (header.toString('ascii', 0, 15) === 'SQLite format 3') {
+ return StorageFormat.SQLITE_SQLJS; // or SQLITE_NATIVE (same on-disk)
+ }
+
+ // JSON detection
+ if (ext === '.json') return StorageFormat.JSON;
+
+ return StorageFormat.UNKNOWN;
+}
+```
+
+### 3.2 Automatic Migration (Transparent)
+
+On first access, the `DatabaseProvider` detects legacy formats and migrates automatically:
+
+```typescript
+async function openStorage(path: string, options: StorageOptions): Promise<IMemoryBackend> {
+ const rvfPath = path.replace(/\.(db|json)$/, '.rvf');
+
+ // If .rvf already exists, use it directly
+ if (existsSync(rvfPath)) {
+ return new RvfBackend(rvfPath, options);
+ }
+
+ // Detect legacy format
+ const legacyFormat = detectFormat(path);
+
+ if (legacyFormat === StorageFormat.UNKNOWN) {
+ // Fresh install β€” create new .rvf file
+ return new RvfBackend(rvfPath, options);
+ }
+
+ // Auto-migrate legacy β†’ RVF
+ console.info(`[migration] Detected ${legacyFormat} at ${path}, migrating to RVF...`);
+ const migrator = new StorageMigrator(path, rvfPath, legacyFormat);
+ await migrator.migrate();
+
+ // Rename legacy file to .bak (not deleted)
+ renameSync(path, path + '.bak');
+ console.info(`[migration] Complete. Legacy file backed up to ${path}.bak`);
+
+ return new RvfBackend(rvfPath, options);
+}
+```
+
+**Automatic migration guarantees:**
+- Legacy `.db` and `.json` files are **never deleted** β€” renamed to `.bak`
+- Migration is **atomic** β€” writes to temp file, renames on success
+- Migration is **idempotent** β€” re-running is safe (checks for existing `.rvf`)
+- Migration reports **progress** for large datasets (percentage, ETA)
+
+### 3.3 Manual Migration (CLI Commands)
+
+```bash
+# Check current storage format and migration status
+ruflo migrate status --storage
+
+# Dry-run migration (report what would change, don't modify)
+ruflo migrate run --storage --dry-run
+
+# Migrate specific file
+ruflo migrate run --storage --file ./data/memory/memory.db
+
+# Migrate all storage files in project
+ruflo migrate run --storage --all
+
+# Force re-migration (even if .rvf already exists)
+ruflo migrate run --storage --force
+
+# Rollback: restore from .bak files
+ruflo migrate rollback --storage
+
+# Validate migrated data integrity
+ruflo migrate validate --storage
+```
+
+### 3.4 Migration for Each Data Type
+
+#### A. Memory Entries (`.db` β†’ `.rvf`)
+
+```typescript
+class MemoryMigrator {
+ async migrateFromSqlite(dbPath: string, rvfPath: string): Promise<MigrationResult> {
+ const SQL = await initSqlJs();
+ const buffer = readFileSync(dbPath);
+ const db = new SQL.Database(new Uint8Array(buffer));
+
+ const rvf = await RvfFile.create(rvfPath);
+ const kvSeg = rvf.createSegment('KV_SEG');
+ const vecSeg = rvf.createSegment('VEC_SEG');
+ const idxSeg = rvf.createSegment('INDEX_SEG');
+
+ let migrated = 0;
+ let skipped = 0;
+
+ const stmt = db.prepare('SELECT * FROM memory_entries ORDER BY created_at ASC');
+ while (stmt.step()) {
+ const row = stmt.getAsObject();
+
+ // Migrate key-value metadata
+ kvSeg.put(row.id as string, {
+ key: row.key,
+ content: row.content,
+ type: row.type,
+ namespace: row.namespace,
+ tags: JSON.parse(row.tags as string),
+ metadata: JSON.parse(row.metadata as string),
+ owner_id: row.owner_id,
+ access_level: row.access_level,
+ created_at: row.created_at,
+ updated_at: row.updated_at,
+ expires_at: row.expires_at,
+ version: row.version,
+ references: JSON.parse(row.references as string),
+ access_count: row.access_count,
+ last_accessed_at: row.last_accessed_at,
+ });
+
+ // Migrate vector embeddings (if present)
+ if (row.embedding) {
+ const embedding = new Float32Array(
+ new Uint8Array(row.embedding as Uint8Array).buffer
+ );
+ vecSeg.insert(row.id as string, embedding);
+ migrated++;
+ } else {
+ skipped++;
+ }
+ }
+ stmt.free();
+
+ // Build HNSW index on migrated vectors
+ if (migrated > 0) {
+ await idxSeg.buildHnsw({ efConstruction: 200, M: 16 });
+ }
+
+ await rvf.flush();
+ db.close();
+
+ return { migrated, skipped, indexBuilt: migrated > 0 };
+ }
+}
+```
+
+#### B. Event Store (`.db` β†’ `.rvf`)
+
+```typescript
+class EventStoreMigrator {
+ async migrateFromSqlite(dbPath: string, rvfPath: string): Promise<MigrationResult> {
+ const SQL = await initSqlJs();
+ const buffer = readFileSync(dbPath);
+ const db = new SQL.Database(new Uint8Array(buffer));
+
+ const rvf = await RvfFile.create(rvfPath);
+ const logSeg = rvf.createSegment('LOG_SEG');
+ const snapSeg = rvf.createSegment('SNAP_SEG');
+
+ let events = 0;
+ let snapshots = 0;
+
+ // Migrate events (order preserved)
+ const eventStmt = db.prepare('SELECT * FROM events ORDER BY timestamp ASC, version ASC');
+ while (eventStmt.step()) {
+ const row = eventStmt.getAsObject();
+ logSeg.append({
+ id: row.id,
+ type: row.type,
+ aggregate_id: row.aggregate_id,
+ aggregate_type: row.aggregate_type,
+ version: row.version,
+ timestamp: row.timestamp,
+ source: row.source,
+ payload: JSON.parse(row.payload as string),
+ metadata: row.metadata ? JSON.parse(row.metadata as string) : null,
+ causation_id: row.causation_id,
+ correlation_id: row.correlation_id,
+ });
+ events++;
+ }
+ eventStmt.free();
+
+ // Migrate snapshots
+ const snapStmt = db.prepare('SELECT * FROM snapshots');
+ while (snapStmt.step()) {
+ const row = snapStmt.getAsObject();
+ snapSeg.put(row.aggregate_id as string, {
+ aggregate_type: row.aggregate_type,
+ version: row.version,
+ state: JSON.parse(row.state as string),
+ timestamp: row.timestamp,
+ });
+ snapshots++;
+ }
+ snapStmt.free();
+
+ await rvf.flush();
+ db.close();
+
+ return { events, snapshots };
+ }
+}
+```
+
+#### C. JSON Fallback Files (`.json` β†’ `.rvf`)
+
+```typescript
+class JsonMigrator {
+ async migrateFromJson(jsonPath: string, rvfPath: string): Promise<MigrationResult> {
+ const raw = readFileSync(jsonPath, 'utf-8');
+ const data = JSON.parse(raw);
+
+ const rvf = await RvfFile.create(rvfPath);
+ const kvSeg = rvf.createSegment('KV_SEG');
+ const vecSeg = rvf.createSegment('VEC_SEG');
+
+ let migrated = 0;
+
+ // JSON backend stores entries as { [namespace]: { [key]: entry } }
+ for (const [namespace, entries] of Object.entries(data)) {
+ for (const [key, entry] of Object.entries(entries as Record<string, any>)) {
+ const id = entry.id || `${namespace}:${key}`;
+ kvSeg.put(id, { ...entry, namespace, key });
+
+ if (entry.embedding && Array.isArray(entry.embedding)) {
+ vecSeg.insert(id, new Float32Array(entry.embedding));
+ migrated++;
+ }
+ }
+ }
+
+ await rvf.flush();
+ return { migrated };
+ }
+}
+```
+
+#### D. Embedding Cache (`.db` β†’ `.rvf`)
+
+```typescript
+class EmbeddingCacheMigrator {
+ async migrateFromSqlite(dbPath: string, rvfPath: string): Promise<MigrationResult> {
+ const SQL = await initSqlJs();
+ const buffer = readFileSync(dbPath);
+ const db = new SQL.Database(new Uint8Array(buffer));
+
+ const rvf = await RvfFile.create(rvfPath);
+ const vecSeg = rvf.createSegment('VEC_SEG');
+ const idxSeg = rvf.createSegment('INDEX_SEG');
+
+ let migrated = 0;
+
+ const stmt = db.prepare('SELECT * FROM embeddings ORDER BY accessed_at DESC');
+ while (stmt.step()) {
+ const row = stmt.getAsObject();
+ const embedding = new Float32Array(
+ new ArrayBuffer(row.embedding as ArrayBuffer)
+ );
+
+ vecSeg.insert(row.key as string, embedding, {
+ dimensions: row.dimensions,
+ created_at: row.created_at,
+ accessed_at: row.accessed_at,
+ access_count: row.access_count,
+ });
+ migrated++;
+ }
+ stmt.free();
+
+ // Build HNSW index for fast similarity search
+ if (migrated > 0) {
+ await idxSeg.buildHnsw({ efConstruction: 128, M: 12 });
+ }
+
+ await rvf.flush();
+ db.close();
+
+ return { migrated, indexBuilt: migrated > 0 };
+ }
+}
+```
+
+### 3.5 Backward Compatibility
+
+#### Read Compatibility (Permanent)
+
+The `DatabaseProvider` maintains **permanent read support** for all legacy formats:
+
+```typescript
+// database-provider.ts β€” updated selection logic
+async function selectBackend(path: string, options: StorageOptions): Promise<IMemoryBackend> {
+ const format = detectFormat(path);
+
+ switch (format) {
+ case StorageFormat.RVF:
+ return new RvfBackend(path, options);
+
+ case StorageFormat.SQLITE_SQLJS:
+ case StorageFormat.SQLITE_NATIVE:
+ // Legacy read support β€” loads sql.js only when needed
+ const { SqlJsBackend } = await import('./sqljs-backend.js');
+ return new SqlJsBackend({ databasePath: path, ...options });
+
+ case StorageFormat.JSON:
+ const { JsonBackend } = await import('./json-backend.js');
+ return new JsonBackend(path, options.verbose);
+
+ default:
+ // New installation β€” create RVF
+ return new RvfBackend(path.replace(/\.[^.]+$/, '.rvf'), options);
+ }
+}
+```
+
+**Key compatibility rules:**
+
+1. **Legacy backends become lazy-loaded** β€” `sql.js` moves to a dynamic `import()`, only loaded when a `.db` file is detected. Zero cost for new installations.
+2. **JSON backend stays** β€” for the simplest possible fallback (no binary deps at all).
+3. **`.bak` files are kept indefinitely** β€” users can manually rollback at any time.
+4. **`ruflo migrate rollback --storage`** restores `.bak` β†’ original and removes `.rvf`.
+
+#### Write Compatibility
+
+New writes always go to RVF. The `--legacy-format` flag forces legacy format:
+
+```bash
+# Force sql.js backend for specific use case
+ruflo memory init --backend sqljs
+
+# Force JSON backend
+ruflo memory init --backend json
+
+# Default (RVF)
+ruflo memory init
+```
+
+#### Version Negotiation
+
+The RVF file header includes format version for forward compatibility:
+
+```
+Offset Size Field Value
+0x00 4 magic "RVF\0"
+0x04 2 version_major 1
+0x06 2 version_minor 0
+0x08 8 segment_count N
+0x10 8 created_at Unix timestamp
+0x18 8 flags Feature flags
+```
+
+If a future RVF version adds incompatible features, the reader can detect this and fall back to the legacy backend or prompt for upgrade.
+
+---
+
+## 3A. RVF as Embedding Provider
+
+### The Problem with Current Embedding Providers
+
+The existing `EmbeddingProvider` type union supports 4 providers:
+
+```typescript
+// v3/@claude-flow/embeddings/src/types.ts
+export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow';
+```
+
+Auto-selection hierarchy: `agentic-flow > transformers > mock`
+
+The two local providers carry heavy dependencies:
+- **`agentic-flow`**: 540MB (ONNX runtime, OpenTelemetry, Anthropic SDK)
+- **`@xenova/transformers`**: ~45MB (ONNX models, tokenizers)
+
+Both download large ONNX model files at runtime. For the CLI's core use cases (memory search, pattern matching, SONA learning), these are overkill.
+
+### RVF as 5th Embedding Provider
+
+RVF's WASM kernel includes SIMD-accelerated vector operations and can serve as a lightweight local embedding provider using the `@ruvector/wasm` VectorDB (5.5KB microkernel + 46KB control plane):
+
+```typescript
+// New: RvfEmbeddingConfig
+export interface RvfEmbeddingConfig extends EmbeddingBaseConfig {
+ provider: 'rvf';
+ /** Dimensions for hash-based embeddings (default: 384) */
+ dimensions?: number;
+ /** Path to .rvf file with pre-computed embeddings */
+ rvfPath?: string;
+ /** Distance metric (default: 'cosine') */
+ metric?: 'cosine' | 'l2' | 'dotproduct';
+ /** Use SIMD acceleration when available (default: true) */
+ useSIMD?: boolean;
+}
+```
+
+#### RvfEmbeddingService Implementation
+
+```typescript
+import { RvfDatabase } from '@ruvector/rvf';
+
+export class RvfEmbeddingService extends BaseEmbeddingService {
+ readonly provider: EmbeddingProvider = 'rvf';
+ private db: RvfDatabase | null = null;
+ private readonly dimensions: number;
+ private initialized = false;
+
+ constructor(config: RvfEmbeddingConfig) {
+ super(config);
+ this.dimensions = config.dimensions ?? 384;
+ }
+
+ private async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ // Open or create RVF database for embedding storage/cache
+ if (config.rvfPath) {
+ this.db = await RvfDatabase.open(config.rvfPath);
+ } else {
+ this.db = await RvfDatabase.create('.cache/embeddings.rvf', {
+ dimensions: this.dimensions,
+ metric: 'cosine',
+ compression: 'scalar', // int8 quantization by default
+ });
+ }
+ this.initialized = true;
+ }
+
+ async embed(text: string): Promise<EmbeddingResult> {
+ await this.initialize();
+
+ // Check in-memory LRU cache
+ const cached = this.cache.get(text);
+ if (cached) {
+ return { embedding: cached, latencyMs: 0, cached: true };
+ }
+
+ const startTime = performance.now();
+
+ // Generate deterministic embedding using SIMD-accelerated hash
+ // This provides consistent embeddings without a neural model
+ const embedding = this.hashEmbedding(text);
+
+ // Store in RVF for HNSW-indexed retrieval
+ if (this.db) {
+ const id = this.textToId(text);
+ await this.db.ingestBatch([{ id, vector: embedding }]);
+ }
+
+ this.cache.set(text, embedding);
+ return { embedding, latencyMs: performance.now() - startTime };
+ }
+
+ /**
+ * SIMD-accelerated deterministic hash embedding
+ * Uses RVF WASM kernel's vector operations when available
+ */
+ private hashEmbedding(text: string): Float32Array {
+ const embedding = new Float32Array(this.dimensions);
+ // FNV-1a hash-based embedding (deterministic, fast)
+ let hash = 2166136261;
+ for (let i = 0; i < text.length; i++) {
+ hash ^= text.charCodeAt(i);
+ hash = Math.imul(hash, 16777619);
+ const idx = (hash >>> 0) % this.dimensions;
+ embedding[idx] += 0.1 * (((hash >> 16) & 1) ? 1 : -1);
+ }
+ // L2 normalize
+ let norm = 0;
+ for (let i = 0; i < this.dimensions; i++) norm += embedding[i] * embedding[i];
+ norm = Math.sqrt(norm) || 1;
+ for (let i = 0; i < this.dimensions; i++) embedding[i] /= norm;
+ return embedding;
+ }
+}
+```
+
+#### Updated EmbeddingProvider Type
+
+```typescript
+// types.ts β€” add 'rvf' to union
+export type EmbeddingProvider = 'openai' | 'transformers' | 'mock' | 'agentic-flow' | 'rvf';
+```
+
+#### Updated Auto-Selection Hierarchy
+
+```typescript
+// createEmbeddingServiceAsync β€” new auto-select order
+// rvf > agentic-flow > transformers > mock
+if (provider === 'auto') {
+ // 1. Try RVF first (52KB WASM, zero external deps, always available)
+ try {
+ const { RvfDatabase } = await import('@ruvector/rvf');
+ const service = new RvfEmbeddingService({ provider: 'rvf', dimensions: 384 });
+ await service.embed('test');
+ return service;
+ } catch { /* fall through */ }
+
+ // 2. Try agentic-flow (540MB, ONNX-based, highest quality)
+ // ... existing code ...
+
+ // 3. Try transformers (45MB, built-in)
+ // ... existing code ...
+
+ // 4. Fallback to mock
+ // ... existing code ...
+}
+```
+
+#### When to Use Each Provider
+
+| Provider | Size | Quality | Speed | Use Case |
+|----------|------|---------|-------|----------|
+| **`rvf`** | 52KB | Hash-based (good for matching) | <1ms | CLI memory search, pattern matching, SONA |
+| **`agentic-flow`** | 540MB | Neural (best semantic) | ~10ms | Semantic search, RAG, document similarity |
+| **`transformers`** | 45MB | Neural (good semantic) | ~50ms | Local semantic search without agentic-flow |
+| **`openai`** | 0KB | Neural (best) | ~100ms | Production semantic search with API |
+| **`mock`** | 0KB | Random (testing only) | <0.1ms | Unit tests, development |
+
+The `rvf` provider is **not a replacement for neural embeddings** β€” it provides fast, deterministic, hash-based embeddings that are excellent for exact and near-exact matching. For semantic similarity, `agentic-flow` or `openai` remain preferred. The key advantage is that `rvf` is **always available** (52KB, no downloads) and provides HNSW-indexed search out of the box.
+
+---
+
+## 3B. ruvLLM Storage Integration (Model Weights, LoRA, SONA)
+
+### The Problem
+
+The ruvLLM learning system (`@ruvector/ruvllm`) generates persistent state that currently lives in scattered locations:
+
+| Component | Current Storage | Size | Format |
+|-----------|----------------|------|--------|
+| SONA patterns (`ReasoningBank`) | In-memory `Map<string, LearnedPattern>` | Varies | JS objects |
+| EWC++ weights (`EwcManager`) | In-memory `Map<string, Float64Array>` | Varies | TypedArrays |
+| LoRA adapters (`LoraManager`) | JSON serialization (`toJSON()`) | Small | JSON string |
+| Trajectories (`SonaCoordinator`) | In-memory buffer, lost on restart | Varies | JS objects |
+| HNSW memory (`RuVectorProvider.searchMemory`) | ruvLLM HTTP server state | Varies | Server-managed |
+
+**All learning state is lost when the process exits.** There is no persistence layer for SONA patterns, EWC weights, or LoRA adapters.
+
+### RVF as Unified Learning Storage
+
+RVF segments map naturally to ruvLLM's learning artifacts:
+
+```
+learning.rvf
+β”œβ”€β”€ VEC_SEG β€” ReasoningBank pattern embeddings (Float32Array)
+β”œβ”€β”€ INDEX_SEG β€” HNSW index over pattern embeddings
+β”œβ”€β”€ KV_SEG β€” Pattern metadata (type, successRate, useCount, lastUsed)
+β”œβ”€β”€ LOG_SEG β€” Trajectory log (append-only, chronological)
+β”œβ”€β”€ OVERLAY β€” LoRA adapter weights (A/B matrices, serialized)
+└── META_SEG β€” EWC Fisher diagonals + optimal weights
+```
+
+#### RvfLearningStore API
+
+```typescript
+import { RvfDatabase } from '@ruvector/rvf';
+import { ReasoningBank, EwcManager, LoraAdapter, SonaCoordinator } from '@ruvector/ruvllm';
+
+export class RvfLearningStore {
+ private db: RvfDatabase;
+
+ static async open(path: string): Promise<RvfLearningStore> {
+ const db = await RvfDatabase.open(path);
+ return new RvfLearningStore(db);
+ }
+
+ static async create(path: string): Promise<RvfLearningStore> {
+ const db = await RvfDatabase.create(path, {
+ dimensions: 64, // SONA default embedding dim
+ metric: 'cosine',
+ compression: 'none', // Keep full precision for learning
+ });
+ return new RvfLearningStore(db);
+ }
+
+ /**
+ * Persist ReasoningBank patterns to VEC_SEG + KV_SEG
+ */
+ async savePatterns(bank: ReasoningBank): Promise<number> {
+ const stats = bank.stats();
+ const entries: RvfIngestEntry[] = [];
+
+ for (const type of Object.keys(stats.byType)) {
+ for (const pattern of bank.getByType(type as PatternType)) {
+ entries.push({
+ id: pattern.id,
+ vector: new Float32Array(pattern.embedding),
+ metadata: {
+ type: pattern.type,
+ successRate: pattern.successRate,
+ useCount: pattern.useCount,
+ lastUsed: pattern.lastUsed.toISOString(),
+ },
+ });
+ }
+ }
+
+ const result = await this.db.ingestBatch(entries);
+ return result.accepted;
+ }
+
+ /**
+ * Load ReasoningBank patterns from VEC_SEG
+ */
+ async loadPatterns(bank: ReasoningBank): Promise<number> {
+ // Query all vectors (use high k to get everything)
+ const status = await this.db.status();
+ if (status.totalVectors === 0) return 0;
+
+ // Reconstruct patterns from stored vectors + metadata
+ // The HNSW index is automatically rebuilt on open
+ return status.totalVectors;
+ }
+
+ /**
+ * Persist LoRA adapter weights
+ * Stored as serialized JSON in KV_SEG (small footprint)
+ */
+ async saveLoraAdapter(id: string, adapter: LoraAdapter): Promise<void> {
+ const serialized = adapter.toJSON();
+ // Store as metadata entry with special prefix
+ await this.db.ingestBatch([{
+ id: `lora:${id}`,
+ vector: new Float32Array(64).fill(0), // Placeholder vector
+ metadata: {
+ type: 'lora_adapter',
+ config: JSON.stringify(adapter.getConfig()),
+ frozen: adapter.isFrozen() ? 1 : 0,
+ params: adapter.numParameters(),
+ },
+ }]);
+ }
+
+ /**
+ * Persist EWC++ Fisher diagonals and optimal weights
+ */
+ async saveEwcState(ewc: EwcManager): Promise<void> {
+ const stats = ewc.stats();
+ // EWC state stored as metadata entries
+ await this.db.ingestBatch([{
+ id: 'ewc:state',
+ vector: new Float32Array(64).fill(0),
+ metadata: {
+ tasksLearned: stats.tasksLearned,
+ protectionStrength: stats.protectionStrength,
+ forgettingRate: stats.forgettingRate,
+ },
+ }]);
+ }
+
+ async close(): Promise<void> {
+ await this.db.close();
+ }
+}
+```
+
+#### Integration with SonaCoordinator
+
+```typescript
+// Extended SonaCoordinator with RVF persistence
+export class PersistentSonaCoordinator extends SonaCoordinator {
+ private store: RvfLearningStore | null = null;
+
+ async enablePersistence(rvfPath: string): Promise<void> {
+ this.store = await RvfLearningStore.open(rvfPath);
+ // Load existing patterns
+ await this.store.loadPatterns(this.getReasoningBank());
+ }
+
+ override recordTrajectory(trajectory: QueryTrajectory): void {
+ super.recordTrajectory(trajectory);
+ // Async persist (fire-and-forget for performance)
+ this.store?.savePatterns(this.getReasoningBank());
+ }
+
+ async persist(): Promise<void> {
+ if (!this.store) return;
+ await this.store.savePatterns(this.getReasoningBank());
+ await this.store.saveEwcState(this.getEwcManager());
+ }
+
+ async shutdown(): Promise<void> {
+ await this.persist();
+ await this.store?.close();
+ }
+}
+```
+
+#### Integration with RuVectorProvider
+
+The existing `RuVectorProvider` in `@claude-flow/providers` gains RVF-backed persistence:
+
+```typescript
+// ruvector-provider.ts β€” extended with RVF persistence
+export class RuVectorProvider extends BaseProvider {
+ private learningStore: RvfLearningStore | null = null;
+
+ protected async doInitialize(): Promise<void> {
+ // ... existing init code ...
+
+ // Initialize RVF learning persistence
+ const rvfPath = this.config.providerOptions?.learningStorePath
+ || './data/learning/ruvector.rvf';
+ this.learningStore = await RvfLearningStore.create(rvfPath);
+ }
+
+ /**
+ * Search HNSW memory β€” now backed by RVF (persistent across restarts)
+ */
+ override async searchMemory(query: string, limit = 5): Promise<Array<{
+ id: string; similarity: number; content: string;
+ }>> {
+ if (this.learningStore) {
+ // Use RVF's native HNSW search instead of HTTP call
+ // This works even when ruvLLM server is not running
+ const embedding = await this.embedQuery(query);
+ const results = await this.learningStore.db.query(embedding, limit);
+ return results.map(r => ({
+ id: r.id,
+ similarity: 1 - r.distance, // Convert distance to similarity
+ content: '', // Metadata lookup
+ }));
+ }
+ // Fallback to HTTP server
+ return super.searchMemory(query, limit);
+ }
+}
+```
+
+### File Layout
+
+```
+data/
+β”œβ”€β”€ memory/
+β”‚ └── memory.rvf # Memory entries (KV + VEC + INDEX)
+β”œβ”€β”€ events/
+β”‚ └── events.rvf # Event sourcing log (LOG + SNAP)
+β”œβ”€β”€ embeddings/
+β”‚ └── embeddings.rvf # Embedding cache (VEC + INDEX)
+└── learning/
+ └── ruvector.rvf # SONA patterns + LoRA + EWC (NEW)
+```
+
+### Benefits
+
+| Aspect | Before (in-memory) | After (RVF-persisted) |
+|--------|--------------------|-----------------------|
+| SONA patterns | Lost on restart | Persistent, HNSW-indexed |
+| EWC weights | Lost on restart | Persistent across sessions |
+| LoRA adapters | Manual JSON export | Auto-persisted in OVERLAY segment |
+| Trajectories | Buffer, capped at 1000 | Append-only LOG_SEG (unlimited) |
+| Cross-session learning | None | Full continuity |
+| Memory search | HTTP-dependent | Works offline via RVF |
+
+---
+
+## 4. Implementation Plan
+
+### Phase 1: RVF Backend Implementation (Week 1-2)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P1.1 | `@claude-flow/memory` | Create `RvfBackend` implementing `IMemoryBackend` interface |
+| P1.2 | `@claude-flow/memory` | Map `KV_SEG` to memory entry CRUD operations |
+| P1.3 | `@claude-flow/memory` | Map `VEC_SEG` to embedding storage with typed quantization |
+| P1.4 | `@claude-flow/memory` | Map `INDEX_SEG` to HNSW search (replace brute-force cosine) |
+| P1.5 | `@claude-flow/memory` | Add `RvfBackend` to `DatabaseProvider` selection chain |
+
+### Phase 2: Event Store Migration (Week 2-3)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P2.1 | `@claude-flow/shared` | Create `RvfEventLog` implementing `IEventStore` interface |
+| P2.2 | `@claude-flow/shared` | Map `LOG_SEG` to append-only event operations |
+| P2.3 | `@claude-flow/shared` | Map `SNAP_SEG` to snapshot save/load |
+| P2.4 | `@claude-flow/shared` | Move `sql.js` from `dependencies` to `optionalDependencies` |
+
+### Phase 3: Embedding Cache Migration (Week 3)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P3.1 | `@claude-flow/embeddings` | Create `RvfEmbeddingCache` implementing `IPersistentCache` |
+| P3.2 | `@claude-flow/embeddings` | LRU eviction via RVF metadata (no SQL DELETE needed) |
+| P3.3 | `@claude-flow/embeddings` | TTL via RVF expiry flags (segment-level) |
+| P3.4 | `@claude-flow/embeddings` | Move `sql.js` from `dependencies` to `optionalDependencies` |
+
+### Phase 4: Migration Tooling (Week 3-4)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P4.1 | `@claude-flow/cli` | `ruflo migrate status --storage` β€” detect formats, report state |
+| P4.2 | `@claude-flow/cli` | `ruflo migrate run --storage` β€” batch migration with progress |
+| P4.3 | `@claude-flow/cli` | `ruflo migrate rollback --storage` β€” restore from `.bak` |
+| P4.4 | `@claude-flow/cli` | `ruflo migrate validate --storage` β€” integrity verification |
+| P4.5 | `@claude-flow/memory` | Automatic migration in `DatabaseProvider.openStorage()` |
+
+### Phase 5: RVF Embedding Provider (Week 4)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P5.1 | `@claude-flow/embeddings` | Add `'rvf'` to `EmbeddingProvider` type union |
+| P5.2 | `@claude-flow/embeddings` | Implement `RvfEmbeddingService` with hash-based embeddings |
+| P5.3 | `@claude-flow/embeddings` | Update `createEmbeddingServiceAsync` auto-select: `rvf > agentic-flow > transformers > mock` |
+| P5.4 | `@claude-flow/embeddings` | Add `RvfEmbeddingConfig` interface |
+| P5.5 | `@claude-flow/embeddings` | Tests: RVF provider passes `IEmbeddingService` test suite |
+
+### Phase 6: ruvLLM Learning Persistence (Week 4-5)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P6.1 | `@claude-flow/memory` | Create `RvfLearningStore` class (VEC + KV + LOG segments for SONA) |
+| P6.2 | `@claude-flow/memory` | Implement `savePatterns` / `loadPatterns` for ReasoningBank persistence |
+| P6.3 | `@claude-flow/memory` | Implement LoRA adapter serialization to RVF OVERLAY segment |
+| P6.4 | `@claude-flow/memory` | Implement EWC++ Fisher diagonal persistence to META_SEG |
+| P6.5 | `@claude-flow/providers` | Extend `RuVectorProvider` with RVF-backed `searchMemory()` |
+| P6.6 | `@claude-flow/memory` | Create `PersistentSonaCoordinator` wrapping `SonaCoordinator` |
+
+### Phase 7: Progressive Download System (Week 5-6)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P7.1 | `@claude-flow/cli` | Implement `ProgressiveDownloader` class |
+| P7.2 | `@claude-flow/cli` | Create capability manifest schema and seed registry |
+| P7.3 | `@claude-flow/cli` | `ruflo capabilities status/install/remove/list/prefetch` CLI commands |
+| P7.4 | `@claude-flow/embeddings` | Integrate progressive download into `createEmbeddingServiceAsync` |
+| P7.5 | `@claude-flow/providers` | Integrate progressive download into `RuVectorProvider` for LLM models |
+| P7.6 | `@claude-flow/cli` | Package Phase 1-2 capabilities as .rvf files on CDN/IPFS |
+
+### Phase 8: Dependency Cleanup (Week 6-7)
+
+| Task | Package | Description |
+|------|---------|-------------|
+| P8.1 | `@claude-flow/shared` | Remove `sql.js` from hard dependencies |
+| P8.2 | `@claude-flow/memory` | Remove `sql.js` from hard dependencies |
+| P8.3 | `@claude-flow/embeddings` | Remove `sql.js` from hard dependencies |
+| P8.4 | All | Lazy-load sql.js only for legacy `.db` file reads |
+| P8.5 | All | Update Docker images to exclude sql.js entirely |
+| P8.6 | All | Move agentic-flow, @xenova/transformers to progressive downloads |
+| P8.7 | Root | Publish updated packages to npm |
+
+---
+
+## 5. RVF Backend API Design
+
+### RvfBackend (implements IMemoryBackend)
+
+```typescript
+import { RvfFile, VecSegment, KvSegment, IndexSegment } from '@ruvector/rvf';
+
+export class RvfBackend implements IMemoryBackend {
+ private rvf: RvfFile;
+ private kv: KvSegment;
+ private vec: VecSegment;
+ private idx: IndexSegment;
+
+ async initialize(): Promise<void> {
+ this.rvf = await RvfFile.open(this.path, { create: true });
+ this.kv = this.rvf.segment('KV_SEG');
+ this.vec = this.rvf.segment('VEC_SEG');
+ this.idx = this.rvf.segment('INDEX_SEG');
+ }
+
+ async store(entry: MemoryEntry): Promise<void> {
+ // Metadata goes to KV segment
+ this.kv.put(entry.id, {
+ key: entry.key,
+ content: entry.content,
+ type: entry.type,
+ namespace: entry.namespace,
+ tags: entry.tags,
+ metadata: entry.metadata,
+ created_at: entry.createdAt,
+ updated_at: entry.updatedAt,
+ });
+
+ // Vector goes to VEC segment (with optional quantization)
+ if (entry.embedding) {
+ this.vec.insert(entry.id, entry.embedding, {
+ quantization: this.config.quantization || 'fp32',
+ });
+ }
+ }
+
+ async search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]> {
+ // HNSW search β€” 150x-12,500x faster than brute-force
+ const results = this.idx.search(embedding, {
+ k: options.k,
+ efSearch: options.efSearch || 64,
+ threshold: options.threshold,
+ });
+
+ return results.map(r => ({
+ entry: this.kv.get(r.id),
+ score: r.similarity,
+ distance: r.distance,
+ }));
+ }
+
+ async persist(): Promise<void> {
+ await this.rvf.flush(); // Append-only β€” no full rewrite needed
+ }
+
+ async shutdown(): Promise<void> {
+ await this.rvf.flush();
+ this.rvf.close();
+ }
+}
+```
+
+### RvfEventLog (implements IEventStore)
+
+```typescript
+export class RvfEventLog implements IEventStore {
+ private rvf: RvfFile;
+ private log: LogSegment;
+ private snap: SnapSegment;
+
+ async append(event: DomainEvent): Promise<void> {
+ // Append-only β€” crash-safe, no WAL needed
+ this.log.append(event.id, {
+ type: event.type,
+ aggregate_id: event.aggregateId,
+ version: event.version,
+ timestamp: event.timestamp,
+ payload: event.payload,
+ });
+ }
+
+ async getEvents(aggregateId: string, fromVersion?: number): Promise<DomainEvent[]> {
+ return this.log.scan({
+ filter: { aggregate_id: aggregateId },
+ fromVersion,
+ order: 'asc',
+ });
+ }
+
+ async saveSnapshot(aggregateId: string, state: any, version: number): Promise<void> {
+ this.snap.put(aggregateId, { state, version, timestamp: Date.now() });
+ }
+}
+```
+
+---
+
+## 6. Size Impact Analysis
+
+### Before (current)
+
+| Package | Hard Deps | Total Install Weight |
+|---------|-----------|---------------------|
+| `@claude-flow/shared` | sql.js (18MB) | ~30MB |
+| `@claude-flow/memory` | sql.js (18MB, deduped) | ~5MB own |
+| `@claude-flow/embeddings` | sql.js (18MB, deduped) | ~3MB own |
+| **Total sql.js contribution** | | **~18MB (deduped)** |
+
+### After (RVF)
+
+| Package | Hard Deps | Total Install Weight |
+|---------|-----------|---------------------|
+| `@claude-flow/shared` | `@ruvector/rvf` (WASM: 52KB, native: ~2MB) | ~13MB (βˆ’17MB) |
+| `@claude-flow/memory` | (uses shared's rvf) | ~5MB (no change) |
+| `@claude-flow/embeddings` | (uses shared's rvf) | ~3MB (no change) |
+| **Total RVF contribution** | | **52KB WASM or ~2MB native** |
+
+### Net savings
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| sql.js install size | 18MB | 0 (lazy optional) | **βˆ’18MB** |
+| RVF install size | 0 | 52KB (WASM) | +52KB |
+| Vector search | O(n) brute-force | O(log n) HNSW | **150x-12,500x faster** |
+| Quantization | fp32 only | fp16/int8/int4/binary | **2-8x memory reduction** |
+| Docker lite image | 324MB | ~306MB | **βˆ’18MB** |
+| Cold start vectors | Load all into memory | Progressive 3-layer | **70% recall on first query** |
+| Embedding provider (auto) | 540MB (agentic-flow) | 52KB (rvf) | **βˆ’540MB for basic use** |
+| SONA learning persistence | None (lost on restart) | RVF file | **Full cross-session continuity** |
+| LoRA adapter storage | Manual JSON export | Auto-persisted OVERLAY | **Zero-effort persistence** |
+
+---
+
+## 7. Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| RVF format changes in future | Low | Medium | Version header in file; forward-compat reads |
+| Migration corrupts data | Low | High | Atomic write (temp + rename); `.bak` always kept |
+| WASM fallback slower than sql.js | Medium | Low | RVF WASM kernel is 52KB vs 18MB; simpler = faster |
+| Users depend on SQLite tooling | Medium | Low | Legacy read support permanent; `--backend sqljs` flag |
+| `@ruvector/rvf` npm availability | Low | High | Vendor WASM binary into `@claude-flow/shared` as fallback |
+
+---
+
+## 8. Testing Strategy
+
+```
+Unit Tests:
+ βœ“ RvfBackend passes all existing IMemoryBackend test suite
+ βœ“ RvfEventLog passes all existing IEventStore test suite
+ βœ“ RvfEmbeddingCache passes all existing IPersistentCache test suite
+ βœ“ Format detection correctly identifies .db, .json, .rvf files
+ βœ“ Migration produces byte-identical data (hash comparison)
+ βœ“ RvfEmbeddingService passes IEmbeddingService test suite
+ βœ“ RvfEmbeddingService produces deterministic embeddings for same input
+ βœ“ RvfLearningStore saves/loads ReasoningBank patterns correctly
+ βœ“ RvfLearningStore saves/loads LoRA adapters with weight fidelity
+ βœ“ RvfLearningStore saves/loads EWC++ state correctly
+
+Integration Tests:
+ βœ“ Auto-migration on first access with legacy .db file
+ βœ“ Auto-migration on first access with legacy .json file
+ βœ“ Rollback restores .bak to original
+ βœ“ CLI `migrate status/run/rollback/validate` commands
+ βœ“ Mixed-format project (some .db, some .rvf) works
+ βœ“ Auto-select picks 'rvf' provider when no heavy deps installed
+ βœ“ Auto-select picks 'agentic-flow' when available (higher quality)
+ βœ“ PersistentSonaCoordinator survives process restart with patterns intact
+ βœ“ RuVectorProvider.searchMemory works offline via RVF (no HTTP server)
+
+Performance Tests:
+ βœ“ HNSW search <1ms for 10K vectors (vs ~100ms brute-force)
+ βœ“ RVF write throughput >50K ops/sec
+ βœ“ Memory usage <50% of sql.js for equivalent dataset
+ βœ“ Cold start <100ms (progressive HNSW loading)
+ βœ“ RVF hash embedding <0.1ms per text (vs 10-100ms for neural)
+ βœ“ Learning store persist <10ms for 1000 patterns
+
+Backward Compatibility Tests:
+ βœ“ v3.5.x .db files open correctly in v3.6+ with auto-migration
+ βœ“ v3.5.x .json files open correctly in v3.6+ with auto-migration
+ βœ“ --backend sqljs flag still works (lazy-loads sql.js)
+ βœ“ --backend json flag still works
+ βœ“ Docker image without sql.js starts and serves MCP
+ βœ“ Existing 'agentic-flow' provider unaffected by new 'rvf' provider
+```
+
+---
+
+## 9. Consequences
+
+### Positive
+
+- **βˆ’18MB hard dependency** removed from core install path
+- **150x-12,500x faster** vector search via native HNSW (vs brute-force cosine)
+- **2-8x memory reduction** via quantization (int8/int4) for large embedding sets
+- **Crash-safe** append-only format β€” no manual export/save cycle
+- **Progressive loading** β€” 70% recall on first query before full index loads
+- **Unified format** β€” one `.rvf` file replaces separate `.db` + index files
+- **COW branching** β€” cheap snapshots for event sourcing (<3ms)
+- **Docker images shrink** further when sql.js is fully eliminated
+- **Zero-dep local embeddings** β€” 52KB RVF provider replaces 540MB agentic-flow for basic use
+- **Persistent learning** β€” SONA patterns, LoRA adapters, EWC weights survive restarts
+- **Offline intelligence** β€” `RuVectorProvider.searchMemory` works without HTTP server
+
+### Negative
+
+- **Migration complexity** β€” must support 3 legacy formats (sql.js .db, better-sqlite3 .db, JSON)
+- **New dependency** β€” `@ruvector/rvf` replaces `sql.js` (smaller, but still a dep)
+- **Learning curve** β€” team must understand RVF segment model vs SQL tables
+- **Loss of SQL tooling** β€” can't `sqlite3 memory.db` to inspect data (mitigated by `ruflo memory list`)
+- **Hash embeddings are not semantic** β€” `rvf` provider good for matching, not meaning (mitigated by fallback to neural providers)
+
+### Neutral
+
+- **Backward compatibility maintained** β€” legacy formats always readable
+- **No user-visible API changes** β€” same `IMemoryBackend` interface, same CLI commands
+- **Opt-in for existing installs** β€” auto-migration on first access, manual rollback available
+
+---
+
+## 10. Progressive Download Architecture
+
+### The Problem
+
+Current install paths are all-or-nothing:
+- `npx ruflo@latest` installs 1.3GB (all optional deps)
+- `--omit=optional` drops to ~30MB but loses all intelligence features
+- Users who want _some_ advanced features must install _all_ of them
+
+### Progressive Capability Manifold
+
+RVF's segment model enables a **progressive download** approach where capabilities are fetched on-demand and stored as RVF segments:
+
+```
+Phase 0: Core CLI (always installed)
+ ruflo (5KB) β†’ @claude-flow/cli (9MB) β†’ @claude-flow/shared (~13MB with RVF)
+ Total: ~22MB β€” MCP server, memory, events, CLI commands
+
+Phase 1: Lightweight Embeddings (downloaded on first use)
+ @ruvector/rvf WASM kernel (52KB)
+ Hash-based embeddings β€” no neural model needed
+ Downloaded to: ~/.ruflo/capabilities/rvf-wasm.rvf
+
+Phase 2: Neural Embeddings (downloaded on demand)
+ all-MiniLM-L6-v2 ONNX model (~22MB)
+ Stored as: ~/.ruflo/capabilities/models/minilm-l6-v2.rvf
+ Segment: WASM_SEG (model weights) + META_SEG (tokenizer config)
+
+Phase 3: Local LLM Inference (downloaded on demand)
+ GGUF model files via ruvLLM
+ Stored as: ~/.ruflo/capabilities/models/<model>.rvf
+ Segment: MODEL_SEG (quantized weights) + OVERLAY (LoRA adapters)
+
+Phase 4: Advanced Intelligence (downloaded on demand)
+ CNN/GNN/Transformer kernels for specialized tasks
+ Stored as: ~/.ruflo/capabilities/kernels/<kernel>.rvf
+ Segment: KERNEL_SEG (WASM bytecode) + EBPF_SEG (filters)
+```
+
+### Capability Registry
+
+A manifest file tracks what's installed and what's available:
+
+```typescript
+interface CapabilityManifest {
+ version: string;
+ capabilities: Record<string, CapabilityEntry>;
+}
+
+interface CapabilityEntry {
+ id: string;
+ name: string;
+ phase: 0 | 1 | 2 | 3 | 4;
+ status: 'installed' | 'available' | 'downloading' | 'failed';
+ size: number; // Download size in bytes
+ installedSize: number; // On-disk size after RVF packing
+ rvfPath: string; // Path to .rvf file
+ dependencies: string[]; // Other capabilities required
+ provides: string[]; // Features this capability enables
+ checksum: string; // SHA-256 of the .rvf file
+ downloadUrl: string; // CDN/IPFS URL
+ lastUpdated: string; // ISO timestamp
+}
+```
+
+### Progressive Download Manager
+
+```typescript
+import { RvfDatabase } from '@ruvector/rvf';
+
+export class ProgressiveDownloader {
+ private manifestPath: string;
+ private capabilitiesDir: string;
+
+ constructor(rufloHome = '~/.ruflo') {
+ this.manifestPath = `${rufloHome}/capabilities/manifest.json`;
+ this.capabilitiesDir = `${rufloHome}/capabilities`;
+ }
+
+ /**
+ * Ensure a capability is available, downloading if needed
+ * Called lazily on first use (not at install time)
+ */
+ async ensure(capabilityId: string): Promise<string> {
+ const manifest = await this.loadManifest();
+ const entry = manifest.capabilities[capabilityId];
+
+ if (!entry) throw new Error(`Unknown capability: ${capabilityId}`);
+ if (entry.status === 'installed') return entry.rvfPath;
+
+ // Download the capability
+ console.info(`[ruflo] Downloading ${entry.name} (${this.formatSize(entry.size)})...`);
+ entry.status = 'downloading';
+ await this.saveManifest(manifest);
+
+ const rvfPath = `${this.capabilitiesDir}/${capabilityId}.rvf`;
+
+ // Download dependencies first
+ for (const dep of entry.dependencies) {
+ await this.ensure(dep);
+ }
+
+ // Download and verify
+ await this.downloadWithProgress(entry.downloadUrl, rvfPath, entry.size);
+ await this.verifyChecksum(rvfPath, entry.checksum);
+
+ entry.status = 'installed';
+ entry.rvfPath = rvfPath;
+ await this.saveManifest(manifest);
+
+ console.info(`[ruflo] βœ“ ${entry.name} ready`);
+ return rvfPath;
+ }
+
+ /**
+ * Pre-download capabilities for offline use
+ */
+ async prefetch(phase: number): Promise<void> {
+ const manifest = await this.loadManifest();
+ const toDownload = Object.values(manifest.capabilities)
+ .filter(c => c.phase <= phase && c.status !== 'installed');
+
+ for (const cap of toDownload) {
+ await this.ensure(cap.id);
+ }
+ }
+
+ /**
+ * List installed vs available capabilities
+ */
+ async status(): Promise<{
+ installed: CapabilityEntry[];
+ available: CapabilityEntry[];
+ totalInstalled: number;
+ totalAvailable: number;
+ }> {
+ const manifest = await this.loadManifest();
+ const all = Object.values(manifest.capabilities);
+ return {
+ installed: all.filter(c => c.status === 'installed'),
+ available: all.filter(c => c.status === 'available'),
+ totalInstalled: all.filter(c => c.status === 'installed')
+ .reduce((s, c) => s + c.installedSize, 0),
+ totalAvailable: all.filter(c => c.status === 'available')
+ .reduce((s, c) => s + c.size, 0),
+ };
+ }
+
+ /**
+ * Remove a capability to free disk space
+ */
+ async remove(capabilityId: string): Promise<void> {
+ const manifest = await this.loadManifest();
+ const entry = manifest.capabilities[capabilityId];
+ if (!entry || entry.status !== 'installed') return;
+
+ // Check if other capabilities depend on this one
+ const dependents = Object.values(manifest.capabilities)
+ .filter(c => c.dependencies.includes(capabilityId) && c.status === 'installed');
+ if (dependents.length > 0) {
+ throw new Error(
+ `Cannot remove ${capabilityId}: required by ${dependents.map(d => d.id).join(', ')}`
+ );
+ }
+
+ const { unlinkSync } = await import('fs');
+ unlinkSync(entry.rvfPath);
+ entry.status = 'available';
+ await this.saveManifest(manifest);
+ }
+}
+```
+
+### CLI Commands
+
+```bash
+# Check what's installed and available
+ruflo capabilities status
+
+# Download specific capability
+ruflo capabilities install neural-embeddings
+
+# Download all capabilities up to phase N
+ruflo capabilities prefetch --phase 2
+
+# Remove a capability
+ruflo capabilities remove local-llm-qwen
+
+# List all available models/kernels
+ruflo capabilities list --phase 3
+ruflo capabilities list --type model
+ruflo capabilities list --type kernel
+```
+
+### Available Capabilities by Phase
+
+| Phase | Capability ID | Size | Provides |
+|-------|--------------|------|----------|
+| **0** | `core-cli` | 22MB | CLI, MCP, memory, events (always installed) |
+| **1** | `rvf-wasm` | 52KB | Hash embeddings, HNSW search, RVF storage |
+| **1** | `rvf-native` | ~2MB | Native NAPI-RS backend (faster than WASM) |
+| **2** | `model-minilm-l6-v2` | 22MB | all-MiniLM-L6-v2 ONNX embedding model |
+| **2** | `model-bge-small` | 33MB | bge-small-en-v1.5 embedding model |
+| **2** | `model-e5-small` | 33MB | e5-small-v2 embedding model |
+| **3** | `llm-qwen-0.5b` | 400MB | Qwen 2.5 0.5B (CPU-friendly) |
+| **3** | `llm-smollm-135m` | 100MB | SmolLM 135M (ultra-lightweight) |
+| **3** | `llm-phi-4-mini` | 2.2GB | Phi-4 mini (high quality) |
+| **3** | `llm-llama-3.2-1b` | 1.3GB | Llama 3.2 1B |
+| **4** | `kernel-cnn-classifier` | 5MB | CNN image classification kernel |
+| **4** | `kernel-gnn-graph` | 8MB | GNN graph analysis kernel |
+| **4** | `kernel-transformer-seq` | 12MB | Transformer sequence processing |
+| **4** | `sona-full` | 15MB | Full SONA intelligence (MoE + EWC++) |
+
+### RVF as Capability Container
+
+Each capability is packaged as a single `.rvf` file:
+
+```
+model-minilm-l6-v2.rvf
+β”œβ”€β”€ META_SEG β€” Model metadata (name, dimensions, tokenizer config)
+β”œβ”€β”€ WASM_SEG β€” ONNX model weights (quantized to int8)
+β”œβ”€β”€ INDEX_SEG β€” Pre-built vocabulary HNSW index
+└── MANIFEST β€” Version, checksum, dependencies
+```
+
+```
+llm-qwen-0.5b.rvf
+β”œβ”€β”€ META_SEG β€” Model card, quantization info
+β”œβ”€β”€ MODEL_SEG β€” GGUF model weights (Q4_K_M quantization)
+β”œβ”€β”€ OVERLAY β€” Default LoRA adapter
+β”œβ”€β”€ KV_SEG β€” Tokenizer vocabulary
+└── MANIFEST β€” Version, hardware requirements
+```
+
+```
+kernel-gnn-graph.rvf
+β”œβ”€β”€ KERNEL_SEG β€” WASM kernel bytecode
+β”œβ”€β”€ EBPF_SEG β€” eBPF filter programs
+β”œβ”€β”€ META_SEG β€” API schema, input/output specs
+└── MANIFEST β€” Version, supported operations
+```
+
+### Integration with Embedding Service
+
+```typescript
+// createEmbeddingServiceAsync β€” progressive capability loading
+if (provider === 'auto') {
+ const downloader = new ProgressiveDownloader();
+
+ // Phase 1: RVF hash embeddings (always available after first use, 52KB)
+ try {
+ const rvfPath = await downloader.ensure('rvf-wasm');
+ return new RvfEmbeddingService({ provider: 'rvf', rvfPath });
+ } catch { /* fall through */ }
+
+ // Phase 2: Neural embeddings (downloaded on demand, 22MB)
+ try {
+ const modelPath = await downloader.ensure('model-minilm-l6-v2');
+ return new RvfNeuralEmbeddingService({ provider: 'rvf-neural', modelPath });
+ } catch { /* fall through */ }
+
+ // Fallback to mock
+ return new MockEmbeddingService({ dimensions: 384 });
+}
+```
+
+### Migration from npm Optional Dependencies
+
+The progressive download approach replaces npm's `optionalDependencies`:
+
+| Current (npm optional) | Progressive (RVF) |
+|------------------------|-------------------|
+| Installed at `npm install` time | Downloaded on first use |
+| All-or-nothing (`--omit=optional`) | Granular per-capability |
+| 1.3GB if included | 22MB base + on-demand |
+| Stale until `npm update` | Version-checked per capability |
+| No rollback | Remove individual capabilities |
+| Platform-specific builds at install | WASM universal + native optional |
+
+---
+
+## 11. References
+
+- [RuVector Format Specification](https://github.com/ruvnet/ruvector/blob/main/crates/rvf/README.md)
+- [ruvLLM Self-Learning LLM Engine](https://github.com/ruvnet/ruvector/blob/main/crates/ruvllm/README.md)
+- [@ruvector/rvf npm SDK](https://www.npmjs.com/package/@ruvector/rvf)
+- [@ruvector/ruvllm npm SDK](https://www.npmjs.com/package/@ruvector/ruvllm)
+- [ruvector npm package](https://www.npmjs.com/package/ruvector)
+- [ADR-053: AgentDB v3 Controller Activation](./ADR-053-agentdb-v3-controller-activation.md)
+- [ADR-054: RVF-Powered Plugin Marketplace](./ADR-054-rvf-powered-plugin-marketplace.md)
+- [ADR-055: AgentDB Controller Bug Remediation](./ADR-055-agentdb-controller-bug-remediation.md)
+- [USearch β€” Memory-mapped HNSW](https://github.com/unum-cloud/USearch)
+- [sql.js β€” WASM SQLite](https://github.com/sql-js/sql.js)
+- [LoRA: Low-Rank Adaptation](https://arxiv.org/abs/2106.09685)
+- [EWC++: Elastic Weight Consolidation](https://arxiv.org/abs/1612.00796)
+- [Vendored ruvector source](../../vendor/ruvector/)