agentic-qe 2.1.2 → 2.2.1

package/dist/core/memory/HNSWVectorMemory.d.ts

@@ -0,0 +1,261 @@
+/**
+ * HNSW Vector Memory - Hierarchical Navigable Small World Index
+ *
+ * High-performance vector similarity search for learning system pattern matching.
+ * Integrates with AgentDB's vector capabilities and RuVector's HNSW implementation.
+ *
+ * Performance Characteristics:
+ * - Search: O(log n) time complexity with HNSW
+ * - Insert: O(log n) amortized
+ * - Memory: ~100 bytes per vector + HNSW overhead
+ *
+ * HNSW Parameters:
+ * - M: Number of connections per node (16-64, default: 32)
+ *   Higher M = better recall, more memory
+ * - efConstruction: Search depth during construction (100-200, default: 200)
+ *   Higher = better quality index, slower build
+ * - efSearch: Search depth during query (50-100, default: 100)
+ *   Higher = better recall, slower search
+ *
+ * Distance Metrics:
+ * - Cosine: Best for semantic similarity (default)
+ * - Euclidean: Best for spatial distance
+ * - Dot Product: Best for normalized vectors
+ *
+ * @module core/memory/HNSWVectorMemory
+ * @version 1.0.0
+ */
+import type { IPatternStore, TestPattern, PatternSearchOptions, PatternSearchResult, PatternStoreStats } from './IPatternStore';
+/**
+ * HNSW Configuration Parameters
+ */
+export interface HNSWConfig {
+    /** Number of bi-directional links per node (16-64, default: 32) */
+    M: number;
+    /** Search depth during index construction (100-200, default: 200) */
+    efConstruction: number;
+    /** Search depth during queries (50-100, default: 100) */
+    efSearch: number;
+    /** Distance metric for similarity calculation */
+    metric: 'cosine' | 'euclidean' | 'dot';
+    /** Vector dimension */
+    dimension: number;
+}
+/**
+ * HNSW Vector Memory Configuration
+ */
+export interface HNSWVectorMemoryConfig extends Partial<HNSWConfig> {
+    /** Path to persistent storage (optional) */
+    storagePath?: string;
+    /** Enable automatic persistence */
+    autoPersist?: boolean;
+    /** Enable performance metrics collection */
+    enableMetrics?: boolean;
+    /** Batch size for bulk operations */
+    batchSize?: number;
+    /** Enable index maintenance (rebalancing, cleanup) */
+    enableMaintenance?: boolean;
+    /** Maintenance interval in milliseconds */
+    maintenanceInterval?: number;
+}
+/**
+ * Search Performance Metrics
+ */
+export interface SearchMetrics {
+    /** Total searches performed */
+    totalSearches: number;
+    /** Average search latency in microseconds */
+    avgLatency: number;
+    /** p50 latency in microseconds */
+    p50Latency: number;
+    /** p99 latency in microseconds */
+    p99Latency: number;
+    /** Queries per second */
+    qps: number;
+    /** Index recall (accuracy) */
+    recall?: number;
+    /** Memory usage in bytes */
+    memoryUsage?: number;
+}
+/**
+ * Index Maintenance Statistics
+ */
+export interface MaintenanceStats {
+    /** Last maintenance timestamp */
+    lastMaintenance: number;
+    /** Number of rebalancing operations */
+    rebalanceCount: number;
+    /** Number of cleanup operations */
+    cleanupCount: number;
+    /** Deleted pattern count */
+    deletedCount: number;
+    /** Index fragmentation percentage (0-100) */
+    fragmentation: number;
+}
+/**
+ * Batch Operation Result
+ */
+export interface BatchResult {
+    /** Number of successful operations */
+    successful: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Errors encountered */
+    errors: Error[];
+}
+/**
+ * HNSW Vector Memory Implementation
+ *
+ * Provides efficient vector similarity search with configurable HNSW parameters.
+ * Integrates with both AgentDB and RuVector backends for flexibility.
+ *
+ * @implements {IPatternStore}
+ */
+export declare class HNSWVectorMemory implements IPatternStore {
+    private config;
+    private initialized;
+    private backend;
+    private hnswConfig;
+    private searchLatencies;
+    private insertLatencies;
+    private totalSearches;
+    private totalInserts;
+    private maintenanceStats;
+    private maintenanceTimer?;
+    constructor(config?: HNSWVectorMemoryConfig);
+    /**
+     * Initialize HNSW vector memory with backend selection
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize AgentDB as fallback backend
+     */
+    private initializeAgentDBBackend;
+    /**
+     * Create IPatternStore adapter for AgentDB
+     */
+    private createAgentDBAdapter;
+    /**
+     * Store a pattern with performance tracking
+     */
+    storePattern(pattern: TestPattern): Promise<void>;
+    /**
+     * Store multiple patterns in batch (optimized)
+     * Returns void to match IPatternStore interface
+     */
+    storeBatch(patterns: TestPattern[]): Promise<void>;
+    /**
+     * Search for similar patterns with performance tracking
+     */
+    searchSimilar(queryEmbedding: number[], options?: PatternSearchOptions): Promise<PatternSearchResult[]>;
+    /**
+     * Batch query multiple vectors (optimized)
+     */
+    searchBatch(queries: Array<{
+        embedding: number[];
+        options?: PatternSearchOptions;
+    }>): Promise<PatternSearchResult[][]>;
+    /**
+     * Get a pattern by ID
+     */
+    getPattern(id: string): Promise<TestPattern | null>;
+    /**
+     * Delete a pattern
+     */
+    deletePattern(id: string): Promise<boolean>;
+    /**
+     * Build or rebuild HNSW index
+     */
+    buildIndex(): Promise<void>;
+    /**
+     * Optimize the index (rebalancing, cleanup)
+     */
+    optimize(): Promise<void>;
+    /**
+     * Get comprehensive statistics
+     */
+    getStats(): Promise<PatternStoreStats>;
+    /**
+     * Get search performance metrics
+     */
+    getSearchMetrics(): SearchMetrics;
+    /**
+     * Get maintenance statistics
+     */
+    getMaintenanceStats(): MaintenanceStats;
+    /**
+     * Get HNSW configuration
+     */
+    getConfig(): HNSWConfig;
+    /**
+     * Update HNSW parameters (requires index rebuild)
+     */
+    updateConfig(config: Partial<HNSWConfig>): Promise<void>;
+    /**
+     * Clear all patterns
+     */
+    clear(): Promise<void>;
+    /**
+     * Shutdown and cleanup
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Record pattern usage (updates lastUsed and usageCount)
+     */
+    recordUsage(id: string): Promise<void>;
+    /**
+     * Get implementation info
+     */
+    getImplementationInfo(): {
+        type: 'ruvector' | 'agentdb' | 'fallback';
+        version: string;
+        features: string[];
+    };
+    /**
+     * Start automatic index maintenance
+     */
+    private startMaintenance;
+    /**
+     * Perform index maintenance
+     */
+    private performMaintenance;
+    /**
+     * Record search latency
+     */
+    private recordSearchLatency;
+    /**
+     * Record insert latency
+     */
+    private recordInsertLatency;
+    /**
+     * Reset performance metrics
+     */
+    private resetMetrics;
+    /**
+     * Ensure initialized
+     */
+    private ensureInitialized;
+    /**
+     * Log configuration on startup
+     */
+    private logConfiguration;
+}
+/**
+ * Create HNSW Vector Memory with default configuration
+ */
+export declare function createHNSWVectorMemory(config?: HNSWVectorMemoryConfig): HNSWVectorMemory;
+/**
+ * Create HNSW Vector Memory optimized for high precision
+ */
+export declare function createHighPrecisionHNSW(storagePath?: string): HNSWVectorMemory;
+/**
+ * Create HNSW Vector Memory optimized for high throughput
+ */
+export declare function createHighThroughputHNSW(storagePath?: string): HNSWVectorMemory;
+/**
+ * Create HNSW Vector Memory with balanced configuration
+ */
+export declare function createBalancedHNSW(storagePath?: string): HNSWVectorMemory;
+//# sourceMappingURL=HNSWVectorMemory.d.ts.map

package/dist/core/memory/HNSWVectorMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HNSWVectorMemory.d.ts","sourceRoot":"","sources":["../../../src/core/memory/HNSWVectorMemory.ts"],"names":[],"mappings":"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"}