π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 IMemoryBackendprivate 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 IMemoryBackendmaxEntries: 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 eventsthis.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 IMemoryBackendthis.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 persistencepersistenceEnabled: true,persistencePath: databasePath,});+ return service.withBackend(hybridBackend);}// Default export