moflo 4.0.2 → 4.0.3

package/v3/@claude-flow/memory/dist/agentdb-backend.d.ts

@@ -0,0 +1,214 @@
+/**
+ * AgentDB Backend - Integration with agentdb@2.0.0-alpha.3.4
+ *
+ * Provides IMemoryBackend implementation using AgentDB with:
+ * - HNSW vector search (150x-12,500x faster than brute-force)
+ * - Native or WASM backend support with graceful fallback
+ * - Optional dependency handling (works without hnswlib-node)
+ * - Seamless integration with HybridBackend
+ *
+ * @module v3/memory/agentdb-backend
+ */
+import { EventEmitter } from 'node:events';
+import { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult, EmbeddingGenerator } from './types.js';
+/**
+ * Configuration for AgentDB Backend
+ */
+export interface AgentDBBackendConfig {
+    /** Database path for persistence */
+    dbPath?: string;
+    /** Namespace for memory organization */
+    namespace?: string;
+    /** Force WASM backend (skip native hnswlib) */
+    forceWasm?: boolean;
+    /** Vector backend: 'auto', 'ruvector', 'hnswlib' */
+    vectorBackend?: 'auto' | 'ruvector' | 'hnswlib';
+    /** Vector dimensions (default: 1536) */
+    vectorDimension?: number;
+    /** HNSW M parameter */
+    hnswM?: number;
+    /** HNSW efConstruction parameter */
+    hnswEfConstruction?: number;
+    /** HNSW efSearch parameter */
+    hnswEfSearch?: number;
+    /** Enable caching */
+    cacheEnabled?: boolean;
+    /** Embedding generator function */
+    embeddingGenerator?: EmbeddingGenerator;
+    /** Maximum entries */
+    maxEntries?: number;
+}
+/**
+ * AgentDB Backend
+ *
+ * Integrates AgentDB for vector search with the V3 memory system.
+ * Provides 150x-12,500x faster search compared to brute-force approaches.
+ *
+ * Features:
+ * - HNSW indexing for fast approximate nearest neighbor search
+ * - Automatic fallback: native hnswlib → ruvector → WASM
+ * - Graceful handling of optional native dependencies
+ * - Semantic search with filtering
+ * - Compatible with HybridBackend for combined SQLite+AgentDB queries
+ */
+export declare class AgentDBBackend extends EventEmitter implements IMemoryBackend {
+    private config;
+    private agentdb;
+    private initialized;
+    private available;
+    private entries;
+    private namespaceIndex;
+    private keyIndex;
+    private numericToStringIdMap;
+    private stats;
+    constructor(config?: AgentDBBackendConfig);
+    /**
+     * Initialize AgentDB
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown AgentDB
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Store a memory entry
+     */
+    store(entry: MemoryEntry): Promise<void>;
+    /**
+     * Get entry by ID
+     */
+    get(id: string): Promise<MemoryEntry | null>;
+    /**
+     * Get entry by key
+     */
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    /**
+     * Update entry
+     */
+    update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    /**
+     * Delete entry
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Query entries
+     */
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /**
+     * Semantic vector search
+     */
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Bulk insert
+     */
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    /**
+     * Bulk delete
+     */
+    bulkDelete(ids: string[]): Promise<number>;
+    /**
+     * Count entries
+     */
+    count(namespace?: string): Promise<number>;
+    /**
+     * List namespaces
+     */
+    listNamespaces(): Promise<string[]>;
+    /**
+     * Clear namespace
+     */
+    clearNamespace(namespace: string): Promise<number>;
+    /**
+     * Get statistics
+     */
+    getStats(): Promise<BackendStats>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Create database schema
+     */
+    private createSchema;
+    /**
+     * Store entry in AgentDB
+     */
+    private storeInAgentDB;
+    /**
+     * Get entry from AgentDB
+     */
+    private getFromAgentDB;
+    /**
+     * Convert agentdb data to MemoryEntry
+     */
+    private dataToEntry;
+    /**
+     * Update entry in AgentDB
+     */
+    private updateInAgentDB;
+    /**
+     * Delete entry from AgentDB
+     */
+    private deleteFromAgentDB;
+    /**
+     * Search with AgentDB HNSW
+     */
+    private searchWithAgentDB;
+    /**
+     * Brute-force vector search fallback
+     */
+    private bruteForceSearch;
+    /**
+     * Semantic search helper
+     */
+    private semanticSearch;
+    /**
+     * In-memory query fallback
+     */
+    private queryInMemory;
+    /**
+     * Update in-memory indexes
+     */
+    private updateIndexes;
+    /**
+     * Convert DB row to MemoryEntry
+     */
+    private rowToEntry;
+    /**
+     * Convert string ID to numeric for HNSW
+     */
+    private stringIdToNumeric;
+    /**
+     * Convert numeric ID back to string using O(1) reverse lookup
+     * PERFORMANCE FIX: Uses pre-built reverse map instead of O(n) linear scan
+     */
+    private numericIdToString;
+    /**
+     * Register string ID in reverse lookup map
+     * Called when storing entries to maintain bidirectional mapping
+     */
+    private registerIdMapping;
+    /**
+     * Unregister string ID from reverse lookup map
+     * Called when deleting entries
+     */
+    private unregisterIdMapping;
+    /**
+     * Cosine similarity (returns value in range [0, 1] where 1 = identical)
+     */
+    private cosineSimilarity;
+    /**
+     * Estimate memory usage
+     */
+    private estimateMemoryUsage;
+    /**
+     * Check if AgentDB is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get underlying AgentDB instance
+     */
+    getAgentDB(): any;
+}
+export default AgentDBBackend;
+//# sourceMappingURL=agentdb-backend.d.ts.map