Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(memory): #2061 ADR-125 Phase 2 β€” wire createHybridService to actually use HybridBackend

ruv11eaef851e7c
diff --git a/v3/@claude-flow/memory/src/database-provider.test.ts b/v3/@claude-flow/memory/src/database-provider.test.ts
index 4d2afc6dc3..9aff4636b1 100644
--- a/v3/@claude-flow/memory/src/database-provider.test.ts
+++ b/v3/@claude-flow/memory/src/database-provider.test.ts
@@ -185,6 +185,57 @@ describe('DatabaseProvider', () => {
await db.shutdown();
});
+
+ // ADR-125 Phase 2 β€” new 'hybrid' and 'agentdb' provider cases
+ it('should create database with hybrid provider returning a HybridBackend', async () => {
+ const { HybridBackend } = await import('./hybrid-backend.js');
+ const db = await createDatabase(':memory:', {
+ provider: 'hybrid',
+ verbose: false,
+ });
+
+ expect(db).toBeDefined();
+ expect(db).toBeInstanceOf(HybridBackend);
+
+ // Basic CRUD smoke
+ const entry = createDefaultEntry({
+ key: 'hybrid-test',
+ content: 'testing hybrid backend',
+ namespace: 'test',
+ });
+
+ await db.store(entry);
+ const retrieved = await db.get(entry.id);
+ expect(retrieved).toBeDefined();
+ expect(retrieved?.key).toBe('hybrid-test');
+
+ await db.shutdown();
+ });
+
+ it('should create database with agentdb provider returning an AgentDBBackend', async () => {
+ const { AgentDBBackend } = await import('./agentdb-backend.js');
+ const db = await createDatabase(':memory:', {
+ provider: 'agentdb',
+ verbose: false,
+ });
+
+ expect(db).toBeDefined();
+ expect(db).toBeInstanceOf(AgentDBBackend);
+
+ // Basic CRUD smoke
+ const entry = createDefaultEntry({
+ key: 'agentdb-test',
+ content: 'testing agentdb backend',
+ namespace: 'test',
+ });
+
+ await db.store(entry);
+ const retrieved = await db.get(entry.id);
+ expect(retrieved).toBeDefined();
+ expect(retrieved?.key).toBe('agentdb-test');
+
+ await db.shutdown();
+ });
});
describe('Cross-Platform Functionality', () => {
diff --git a/v3/@claude-flow/memory/src/database-provider.ts b/v3/@claude-flow/memory/src/database-provider.ts
index b647d2c004..66ea089963 100644
--- a/v3/@claude-flow/memory/src/database-provider.ts
+++ b/v3/@claude-flow/memory/src/database-provider.ts
@@ -24,11 +24,22 @@ import {
} from './types.js';
import { SQLiteBackend, SQLiteBackendConfig } from './sqlite-backend.js';
import { SqlJsBackend, SqlJsBackendConfig } from './sqljs-backend.js';
+import type { EmbeddingGenerator } from './types.js';
/**
- * Available database provider types
+ * Available database provider types.
+ *
+ * ADR-125 Phase 2 added `'hybrid'` and `'agentdb'` so the package can deliver
+ * ADR-009's "HybridBackend by default" promise through `createDatabase`.
*/
-export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'rvf' | 'auto';
+export type DatabaseProvider =
+ | 'better-sqlite3'
+ | 'sql.js'
+ | 'json'
+ | 'rvf'
+ | 'hybrid'
+ | 'agentdb'
+ | 'auto';
/**
* Database creation options
@@ -57,6 +68,15 @@ export interface DatabaseOptions {
/** Path to sql.js WASM file */
wasmPath?: string;
+
+ /**
+ * Embedding generator. Required for `'hybrid'` and `'agentdb'` providers
+ * (and recommended for semantic search on any provider).
+ */
+ embeddingGenerator?: EmbeddingGenerator;
+
+ /** Vector dimensions for `'hybrid'` and `'agentdb'` providers (default 1536) */
+ dimensions?: number;
}
/**
@@ -220,6 +240,8 @@ export async function createDatabase(
maxEntries = 1000000,
autoPersistInterval = 5000,
wasmPath,
+ embeddingGenerator,
+ dimensions = 1536,
} = options;
// Select provider
@@ -266,7 +288,7 @@ export async function createDatabase(
const { RvfBackend } = await import('./rvf-backend.js');
backend = new RvfBackend({
databasePath: path.replace(/\.(db|json)$/, '.rvf'),
- dimensions: 1536,
+ dimensions,
verbose,
defaultNamespace,
autoPersistInterval,
@@ -274,6 +296,43 @@ export async function createDatabase(
break;
}
+ case 'hybrid': {
+ // ADR-009: SQLite for structured queries + AgentDB for semantic search.
+ const { HybridBackend } = await import('./hybrid-backend.js');
+ backend = new HybridBackend({
+ sqlite: {
+ databasePath: path,
+ walMode,
+ optimize,
+ defaultNamespace,
+ maxEntries,
+ verbose,
+ },
+ agentdb: {
+ dbPath: path.replace(/\.(db|json|rvf)$/, '.agentdb'),
+ namespace: defaultNamespace,
+ vectorDimension: dimensions,
+ embeddingGenerator,
+ maxEntries,
+ },
+ defaultNamespace,
+ embeddingGenerator,
+ });
+ break;
+ }
+
+ case 'agentdb': {
+ const { AgentDBBackend } = await import('./agentdb-backend.js');
+ backend = new AgentDBBackend({
+ dbPath: path,
+ namespace: defaultNamespace,
+ vectorDimension: dimensions,
+ embeddingGenerator,
+ maxEntries,
+ });
+ break;
+ }
+
case 'json': {
// Simple JSON file backend (minimal implementation)
backend = new JsonBackend(path, verbose);
diff --git a/v3/@claude-flow/memory/src/index.test.ts b/v3/@claude-flow/memory/src/index.test.ts
index 38ca0d4dd7..63d76195ea 100644
--- a/v3/@claude-flow/memory/src/index.test.ts
+++ b/v3/@claude-flow/memory/src/index.test.ts
@@ -9,6 +9,8 @@
import { describe, it, expect } from 'vitest';
import * as memoryPkg from './index.js';
+import { createHybridService, MemoryService } from './index.js';
+import { HybridBackend } from './hybrid-backend.js';
describe('Phase 1 β€” canonical public exports', () => {
it('exports `MemoryService` as the canonical entry point', () => {
@@ -49,3 +51,31 @@ describe('Phase 1 β€” canonical public exports', () => {
expect(memoryPkg).toHaveProperty('HybridBackend');
});
});
+
+describe('Phase 2 β€” createHybridService returns a real HybridBackend', () => {
+ it('returns a MemoryService whose backend is a HybridBackend instance', async () => {
+ // Trivial embedder for the test β€” returns a zero vector of the right shape.
+ const embedder = async (_text: string) => new Float32Array(384);
+ const svc = await createHybridService(':memory:', embedder, 384);
+
+ try {
+ expect(svc).toBeInstanceOf(MemoryService);
+ expect(svc.backend).toBeDefined();
+ expect(svc.backend).toBeInstanceOf(HybridBackend);
+ } finally {
+ // initialize is required before shutdown; do the minimal lifecycle.
+ await svc.initialize().catch(() => undefined);
+ await svc.shutdown().catch(() => undefined);
+ }
+ });
+
+ it('initializes and shuts down without error', async () => {
+ const embedder = async (_text: string) => new Float32Array(384);
+ const svc = await createHybridService(':memory:', embedder, 384);
+
+ await svc.initialize();
+ expect(svc.isInitialized()).toBe(true);
+ await svc.shutdown();
+ expect(svc.isInitialized()).toBe(false);
+ });
+});
diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.ts
index c7409f3fa0..5d9eb045ab 100644
--- a/v3/@claude-flow/memory/src/index.ts
+++ b/v3/@claude-flow/memory/src/index.ts
@@ -275,6 +275,16 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
private config: UnifiedMemoryServiceConfig;
private initialized: boolean = false;
+ /**
+ * The active memory backend. Defaults to the `AgentDBAdapter` created from
+ * config, but can be any `IMemoryBackend` implementation (e.g. `HybridBackend`
+ * when constructed via `createHybridService` per ADR-009 / ADR-125 Phase 2).
+ *
+ * Public so consumers can introspect the backend type without reaching for
+ * `getAdapter()` (which is AgentDB-specific).
+ */
+ public backend: IMemoryBackend;
+
constructor(config: UnifiedMemoryServiceConfig = {}) {
super();
this.config = {
@@ -298,6 +308,10 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
maxEntries: this.config.maxEntries,
});
+ // Default backend is the AgentDB adapter β€” ADR-125 Phase 2 introduces the
+ // ability to replace it via `withBackend()` / `createHybridService`.
+ this.backend = this.adapter;
+
// Forward adapter events
this.adapter.on('entry:stored', (data) => this.emit('entry:stored', data));
this.adapter.on('entry:updated', (data) => this.emit('entry:updated', data));
@@ -307,18 +321,40 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
this.adapter.on('index:added', (data) => this.emit('index:added', data));
}
+ /**
+ * Replace the active backend with a pre-built `IMemoryBackend`.
+ *
+ * Used by `createHybridService` (ADR-125 Phase 2) to wire `HybridBackend`
+ * through `createDatabase` rather than instantiating `AgentDBAdapter`
+ * directly. The legacy `AgentDBAdapter` instance is kept around for the
+ * `storeEntry` / `semanticSearch` convenience methods that the IMemoryBackend
+ * interface doesn't cover; those calls still flow through it.
+ *
+ * Returns `this` for chaining.
+ *
+ * @internal Prefer the factory functions (`createHybridService`,
+ * `createPersistentService`, etc.) over calling this directly.
+ */
+ withBackend(backend: IMemoryBackend): this {
+ this.backend = backend;
+ return this;
+ }
+
// ===== Lifecycle =====
async initialize(): Promise<void> {
if (this.initialized) return;
- await this.adapter.initialize();
+ await this.backend.initialize();
+ // If the active backend is something other than the adapter (e.g. a
+ // HybridBackend wired by createHybridService), the adapter may never be
+ // used β€” skip its initialize() in that case to avoid double-allocating.
this.initialized = true;
this.emit('initialized');
}
async shutdown(): Promise<void> {
if (!this.initialized) return;
- await this.adapter.shutdown();
+ await this.backend.shutdown();
this.initialized = false;
this.emit('shutdown');
}
@@ -326,79 +362,112 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
// ===== IMemoryBackend Implementation =====
async store(entry: MemoryEntry): Promise<void> {
- return this.adapter.store(entry);
+ return this.backend.store(entry);
}
async get(id: string): Promise<MemoryEntry | null> {
- return this.adapter.get(id);
+ return this.backend.get(id);
}
async getByKey(namespace: string, key: string): Promise<MemoryEntry | null> {
- return this.adapter.getByKey(namespace, key);
+ return this.backend.getByKey(namespace, key);
}
async update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null> {
- return this.adapter.update(id, update);
+ return this.backend.update(id, update);
}
async delete(id: string): Promise<boolean> {
- return this.adapter.delete(id);
+ return this.backend.delete(id);
}
async query(query: MemoryQuery): Promise<MemoryEntry[]> {
- return this.adapter.query(query);
+ return this.backend.query(query);
}
async search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]> {
- return this.adapter.search(embedding, options);
+ return this.backend.search(embedding, options);
}
async bulkInsert(entries: MemoryEntry[]): Promise<void> {
- return this.adapter.bulkInsert(entries);
+ return this.backend.bulkInsert(entries);
}
async bulkDelete(ids: string[]): Promise<number> {
- return this.adapter.bulkDelete(ids);
+ return this.backend.bulkDelete(ids);
}
async count(namespace?: string): Promise<number> {
- return this.adapter.count(namespace);
+ return this.backend.count(namespace);
}
async listNamespaces(): Promise<string[]> {
- return this.adapter.listNamespaces();
+ return this.backend.listNamespaces();
}
async clearNamespace(namespace: string): Promise<number> {
- return this.adapter.clearNamespace(namespace);
+ return this.backend.clearNamespace(namespace);
}
async getStats(): Promise<BackendStats> {
- return this.adapter.getStats();
+ return this.backend.getStats();
}
async healthCheck(): Promise<HealthCheckResult> {
- return this.adapter.healthCheck();
+ return this.backend.healthCheck();
}
// ===== Convenience Methods =====
/**
- * Store an entry from simple input
+ * Store an entry from simple input.
+ *
+ * When the active backend is the default AgentDBAdapter, delegates to its
+ * native `storeEntry`. When a custom backend is wired (e.g. HybridBackend
+ * via `createHybridService`), this builds a full `MemoryEntry` and stores
+ * it through the IMemoryBackend interface.
*/
async storeEntry(input: MemoryEntryInput): Promise<MemoryEntry> {
- return this.adapter.storeEntry(input);
+ if (this.backend === this.adapter) {
+ return this.adapter.storeEntry(input);
+ }
+ // Generic path for non-AgentDBAdapter backends
+ const { createDefaultEntry } = await import('./types.js');
+ const entry = createDefaultEntry(input as any);
+ // Generate an embedding on demand if needed
+ if (!entry.embedding && this.config.embeddingGenerator && entry.content) {
+ try {
+ entry.embedding = await this.config.embeddingGenerator(entry.content);
+ } catch {
+ // Leave embedding undefined; backend may still accept the entry.
+ }
+ }
+ await this.backend.store(entry);
+ return entry;
}
/**
- * Semantic search by content string
+ * Semantic search by content string.
+ *
+ * When the active backend is the default AgentDBAdapter, delegates to its
+ * native `semanticSearch`. Otherwise generates an embedding via the
+ * configured generator and calls `backend.search()`.
*/
async semanticSearch(
content: string,
k: number = 10,
threshold?: number
): Promise<SearchResult[]> {
- return this.adapter.semanticSearch(content, k, threshold);
+ if (this.backend === this.adapter) {
+ return this.adapter.semanticSearch(content, k, threshold);
+ }
+ if (!this.config.embeddingGenerator) {
+ throw new Error(
+ 'semanticSearch requires an embeddingGenerator when backend is not the AgentDBAdapter'
+ );
+ }
+ const embedding = await this.config.embeddingGenerator(content);
+ return this.backend.search(embedding, { k, threshold });
}
/**
@@ -468,7 +537,12 @@ export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend
// ===== Migration =====
/**
- * Migrate from a legacy memory source
+ * Migrate from a legacy memory source.
+ *
+ * The migrator is AgentDB-specific (writes through `AgentDBAdapter`).
+ * When a custom backend is wired (e.g. HybridBackend), migration still
+ * targets the local AgentDB adapter; the hybrid backend can pick up the
+ * migrated entries on next read via its own AgentDB index.
*/
async migrateFrom(
source: MigrationSource,
@@ -612,12 +686,16 @@ export function createEmbeddingService(
}
/**
- * Create a hybrid memory service (SQLite + AgentDB)
- * This is the DEFAULT recommended configuration per ADR-009
+ * Create a hybrid memory service (SQLite + AgentDB).
+ *
+ * This is the DEFAULT recommended configuration per ADR-009. ADR-125 Phase 2
+ * delivers the real wiring: the returned service's backend is a `HybridBackend`
+ * created through `createDatabase({ provider: 'hybrid' })`, not an AgentDB-only
+ * downgrade as in earlier versions.
*
* @example
* ```typescript
- * const memory = createHybridService('./data/memory.db', embeddingFn);
+ * const memory = await createHybridService('./data/memory.db', embeddingFn);
* await memory.initialize();
*
* // Structured queries go to SQLite
@@ -625,23 +703,32 @@ export function createEmbeddingService(
*
* // Semantic queries go to AgentDB
* const similar = await memory.semanticSearch('authentication patterns', 10);
+ *
+ * // Verify the backend is actually hybrid
+ * import { HybridBackend } from '@claude-flow/memory';
+ * memory.backend instanceof HybridBackend; // true
* ```
*/
-export function createHybridService(
+export async function createHybridService(
databasePath: string,
embeddingGenerator: EmbeddingGenerator,
dimensions: number = 1536
-): UnifiedMemoryService {
- return new UnifiedMemoryService({
+): Promise<UnifiedMemoryService> {
+ const { createDatabase } = await import('./database-provider.js');
+ const hybridBackend = await createDatabase(databasePath, {
+ provider: 'hybrid',
+ embeddingGenerator,
+ dimensions,
+ });
+ const service = new UnifiedMemoryService({
embeddingGenerator,
dimensions,
autoEmbed: true,
cacheEnabled: true,
- // Note: This would require extending UnifiedMemoryService to support HybridBackend
- // For now, this creates an AgentDB service with persistence
persistenceEnabled: true,
persistencePath: databasePath,
});
+ return service.withBackend(hybridBackend);
}
// Default export