@skillsmith/core 0.4.0 → 0.4.2

package/dist/src/embeddings/hnsw-store.js

@@ -1,210 +1,57 @@
 /**
  * SMI-1519: HNSW Embedding Store
  *
- * High-performance vector storage using HNSW (Hierarchical Navigable Small World)
- * index for fast approximate nearest neighbor (ANN) search.
- *
- * Features:
- * - O(log n) similarity search vs O(n) brute-force (150x faster)
- * - SQLite for metadata persistence (skill_id, text, created_at)
- * - Graceful fallback to brute-force if HNSW unavailable
- * - Compatible with existing EmbeddingService interface
- * - Uses claude-flow V3 VectorDB API with automatic fallback
- *
- * Enable via environment variable: SKILLSMITH_USE_HNSW=true
+ * High-performance vector storage using HNSW index for fast ANN search.
+ * Uses claude-flow V3 VectorDB API with automatic fallback to brute-force.
  *
+ * Enable via: SKILLSMITH_USE_HNSW=true
  * @see ADR-009: Embedding Service Fallback Strategy
  */
 import Database from 'better-sqlite3';
-// ============================================================================
-// Default Configuration
-// ============================================================================
-/**
- * Default HNSW configuration optimized for skill embeddings.
- * Tuned for ~10k-100k skills with balanced speed/recall.
- */
-export const DEFAULT_HNSW_CONFIG = {
-    m: 16,
-    efConstruction: 200,
-    efSearch: 100,
-    dimensions: 384, // all-MiniLM-L6-v2
-};
-/**
- * HNSW configuration presets for different use cases
- */
-export const HNSW_PRESETS = {
-    /** Fast search, lower memory, suitable for <10k vectors */
-    small: {
-        m: 8,
-        efConstruction: 100,
-        efSearch: 50,
-        dimensions: 384,
-    },
-    /** Balanced performance, suitable for 10k-100k vectors */
-    medium: {
-        m: 16,
-        efConstruction: 200,
-        efSearch: 100,
-        dimensions: 384,
-    },
-    /** High recall, suitable for 100k-1M vectors */
-    large: {
-        m: 32,
-        efConstruction: 400,
-        efSearch: 150,
-        dimensions: 384,
-    },
-    /** Maximum recall, suitable for >1M vectors or critical accuracy */
-    xlarge: {
-        m: 48,
-        efConstruction: 500,
-        efSearch: 200,
-        dimensions: 384,
-    },
-};
-// ============================================================================
-// Class Skeleton
-// ============================================================================
+export { DEFAULT_HNSW_CONFIG, HNSW_PRESETS } from './hnsw-store.types.js';
+// Re-export factory functions
+export { createHNSWStore, isHNSWAvailable, loadHNSWLib } from './hnsw-store.helpers.js';
+import { DEFAULT_HNSW_CONFIG } from './hnsw-store.types.js';
+import { shouldUseHNSW, validateDimensions, estimateMemoryUsage } from './hnsw-store.helpers.js';
 /**
  * High-performance embedding storage using HNSW index.
- *
- * Provides O(log n) approximate nearest neighbor search while maintaining
- * compatibility with the existing EmbeddingService interface.
- *
- * @example
- * ```typescript
- * // Basic usage
- * const store = new HNSWEmbeddingStore({
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- * });
- *
- * // Store embeddings
- * store.storeEmbedding('skill-1', embedding1, 'Jest testing framework helper');
- * store.storeEmbedding('skill-2', embedding2, 'Vitest testing utilities');
- *
- * // Find similar
- * const results = store.findSimilar(queryEmbedding, 10);
- * // [{ skillId: 'skill-1', score: 0.95 }, { skillId: 'skill-2', score: 0.87 }, ...]
- *
- * // Clean up
- * store.close();
- * ```
- *
- * @example
- * ```typescript
- * // With custom HNSW config for large dataset
- * const store = new HNSWEmbeddingStore({
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- *   hnswConfig: HNSW_PRESETS.large,
- *   maxElements: 500000,
- * });
- * ```
+ * Provides O(log n) approximate nearest neighbor search with SQLite persistence.
  */
 export class HNSWEmbeddingStore {
-    // -------------------------------------------------------------------------
-    // Private Fields
-    // -------------------------------------------------------------------------
-    /** SQLite database for metadata */
     db = null;
-    /** HNSW index instance (from hnswlib-node) */
     index = null;
-    /** Whether HNSW is enabled (false = brute-force fallback) */
     hnswEnabled;
-    /** Merged HNSW configuration */
     config;
-    /** Maximum index capacity */
     maxElements;
-    /** Path to HNSW index file */
     indexPath;
-    /** Distance metric */
     distanceMetric;
-    /** Auto-save flag */
     autoSave;
-    /** Map of skill IDs to internal HNSW labels (for reverse lookup) */
     skillIdToLabel = new Map();
-    /** Map of HNSW labels to skill IDs */
     labelToSkillId = new Map();
-    /** Next available label for HNSW insertion */
     nextLabel = 0;
-    // -------------------------------------------------------------------------
-    // Constructor
-    // -------------------------------------------------------------------------
-    /**
-     * Create a new HNSWEmbeddingStore instance.
-     *
-     * @param options - Configuration options
-     *
-     * @example
-     * ```typescript
-     * // Default configuration (auto-detects HNSW availability)
-     * const store = new HNSWEmbeddingStore();
-     *
-     * // With persistence
-     * const store = new HNSWEmbeddingStore({
-     *   dbPath: './embeddings.db',
-     *   indexPath: './embeddings.hnsw',
-     * });
-     *
-     * // Force brute-force fallback
-     * const store = new HNSWEmbeddingStore({ useHNSW: false });
-     * ```
-     */
-    /** V3 VectorDB instance (if initialized) */
     vectorDB = null;
-    /** Promise for async initialization */
     initPromise = null;
     constructor(options = {}) {
-        // Determine HNSW mode from options or environment
-        this.hnswEnabled = this.shouldUseHNSW(options.useHNSW);
-        // Merge configuration with defaults
-        this.config = {
-            ...DEFAULT_HNSW_CONFIG,
-            ...options.hnswConfig,
-        };
+        this.hnswEnabled = shouldUseHNSW(options.useHNSW);
+        this.config = { ...DEFAULT_HNSW_CONFIG, ...options.hnswConfig };
         this.maxElements = options.maxElements ?? 100000;
         this.indexPath = options.indexPath;
         this.distanceMetric = options.distanceMetric ?? 'cosine';
         this.autoSave = options.autoSave ?? false;
-        // Initialize SQLite database
         if (options.dbPath) {
             this.initDatabase(options.dbPath);
         }
-        // Initialize HNSW index asynchronously (if enabled)
+        // IMPORTANT: Keep dynamic import here for V3 lazy loading / graceful degradation
         if (this.hnswEnabled) {
             this.initPromise = this.initHNSWIndex();
         }
     }
-    /**
-     * Ensure the store is fully initialized.
-     * Call this before operations that require the HNSW index.
-     */
     async ensureInitialized() {
-        if (this.initPromise) {
+        if (this.initPromise)
             await this.initPromise;
-        }
     }
-    // -------------------------------------------------------------------------
-    // Public Methods (IEmbeddingStore Interface)
-    // -------------------------------------------------------------------------
-    /**
-     * Store an embedding with its metadata.
-     *
-     * Inserts the vector into both HNSW index (for fast search) and
-     * SQLite (for metadata persistence).
-     *
-     * @param skillId - Unique identifier for the skill
-     * @param embedding - Vector embedding (must match configured dimensions)
-     * @param text - Original text that was embedded
-     * @throws Error if embedding dimensions don't match configuration
-     */
     storeEmbedding(skillId, embedding, text) {
-        // Validate embedding dimensions
-        if (embedding.length !== this.config.dimensions) {
-            throw new Error(`Embedding dimension mismatch: got ${embedding.length}, expected ${this.config.dimensions}`);
-        }
-        // Store in SQLite (metadata + embedding blob for brute-force fallback)
+        validateDimensions(embedding, this.config.dimensions, 'Embedding');
         if (this.db) {
             const buffer = Buffer.from(embedding.buffer);
             const stmt = this.db.prepare(`
@@ -213,49 +60,28 @@ export class HNSWEmbeddingStore {
       `);
             stmt.run(skillId, buffer, text);
         }
-        // Insert into V3 VectorDB (HNSW index)
         if (this.vectorDB) {
-            // VectorDB.insert may be sync or async depending on backend
             const result = this.vectorDB.insert(embedding, skillId, { text });
             if (result instanceof Promise) {
-                // Fire and forget for sync interface, but log errors
                 result.catch((err) => {
                     console.warn(`[HNSWEmbeddingStore] Failed to insert into VectorDB: ${err}`);
                 });
             }
         }
     }
-    /**
-     * Retrieve a stored embedding by skill ID.
-     *
-     * @param skillId - Unique identifier for the skill
-     * @returns The embedding if found, null otherwise
-     */
     getEmbedding(skillId) {
         if (!this.db)
             return null;
-        const stmt = this.db.prepare(`
-      SELECT embedding FROM skill_embeddings WHERE skill_id = ?
-    `);
+        const stmt = this.db.prepare('SELECT embedding FROM skill_embeddings WHERE skill_id = ?');
         const row = stmt.get(skillId);
         if (!row)
             return null;
         return new Float32Array(row.embedding.buffer.slice(row.embedding.byteOffset, row.embedding.byteOffset + row.embedding.byteLength));
     }
-    /**
-     * Get all stored embeddings.
-     *
-     * Note: For large datasets, consider using findSimilar() instead
-     * to avoid loading all vectors into memory.
-     *
-     * @returns Map of skill IDs to their embeddings
-     */
     getAllEmbeddings() {
         if (!this.db)
             return new Map();
-        const stmt = this.db.prepare(`
-      SELECT skill_id, embedding FROM skill_embeddings
-    `);
+        const stmt = this.db.prepare('SELECT skill_id, embedding FROM skill_embeddings');
         const rows = stmt.all();
         const result = new Map();
         for (const row of rows) {
@@ -264,102 +90,51 @@ export class HNSWEmbeddingStore {
         }
         return result;
     }
-    /**
-     * Find most similar embeddings to a query vector.
-     *
-     * Uses HNSW for O(log n) approximate search when available,
-     * falls back to O(n) brute-force cosine similarity otherwise.
-     *
-     * @param queryEmbedding - Query vector (must match configured dimensions)
-     * @param topK - Number of results to return (default: 10)
-     * @returns Array of skill IDs with similarity scores, sorted descending
-     */
     findSimilar(queryEmbedding, topK = 10) {
-        // Validate query dimensions
-        if (queryEmbedding.length !== this.config.dimensions) {
-            throw new Error(`Query dimension mismatch: got ${queryEmbedding.length}, expected ${this.config.dimensions}`);
-        }
-        // Try HNSW search first (if available)
+        validateDimensions(queryEmbedding, this.config.dimensions);
         if (this.vectorDB) {
             try {
-                // VectorDB.search may be sync or async
                 const searchResult = this.vectorDB.search(queryEmbedding, topK);
-                // Handle async case by returning empty and logging
-                // (sync interface limitation - caller should use findSimilarAsync for async)
                 if (searchResult instanceof Promise) {
-                    // For sync interface, fall back to brute-force
-                    console.warn('[HNSWEmbeddingStore] VectorDB.search returned Promise, using brute-force fallback');
+                    console.warn('[HNSWEmbeddingStore] VectorDB.search returned Promise, using brute-force');
                 }
                 else {
-                    // Convert VectorDB results to SimilarityResult format
-                    return searchResult.map((result) => ({
-                        skillId: result.id,
-                        score: result.score,
-                    }));
+                    return searchResult.map((r) => ({ skillId: r.id, score: r.score }));
                 }
             }
             catch (err) {
-                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back to brute-force: ${err}`);
+                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back: ${err}`);
             }
         }
-        // Brute-force fallback: compute cosine similarity for all embeddings
+        // Brute-force fallback
         const allEmbeddings = this.getAllEmbeddings();
         const results = [];
         for (const [skillId, embedding] of allEmbeddings) {
-            const score = this.cosineSimilarity(queryEmbedding, embedding);
-            results.push({ skillId, score });
+            results.push({ skillId, score: this.cosineSimilarity(queryEmbedding, embedding) });
         }
-        // Sort by similarity score descending and return topK
         results.sort((a, b) => b.score - a.score);
         return results.slice(0, topK);
     }
-    /**
-     * Async version of findSimilar for backends that require async search.
-     *
-     * @param queryEmbedding - Query vector (must match configured dimensions)
-     * @param topK - Number of results to return (default: 10)
-     * @returns Promise resolving to array of skill IDs with similarity scores
-     */
     async findSimilarAsync(queryEmbedding, topK = 10) {
-        // Ensure HNSW is initialized
         await this.ensureInitialized();
-        // Validate query dimensions
-        if (queryEmbedding.length !== this.config.dimensions) {
-            throw new Error(`Query dimension mismatch: got ${queryEmbedding.length}, expected ${this.config.dimensions}`);
-        }
-        // Try HNSW search first (if available)
+        validateDimensions(queryEmbedding, this.config.dimensions);
         if (this.vectorDB) {
             try {
                 const searchResult = this.vectorDB.search(queryEmbedding, topK);
                 const results = searchResult instanceof Promise ? await searchResult : searchResult;
-                return results.map((result) => ({
-                    skillId: result.id,
-                    score: result.score,
-                }));
+                return results.map((r) => ({ skillId: r.id, score: r.score }));
             }
             catch (err) {
-                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back to brute-force: ${err}`);
+                console.warn(`[HNSWEmbeddingStore] HNSW search failed, falling back: ${err}`);
             }
         }
-        // Brute-force fallback
         return this.findSimilar(queryEmbedding, topK);
     }
-    /**
-     * Compute cosine similarity between two embeddings.
-     *
-     * @param a - First embedding
-     * @param b - Second embedding
-     * @returns Similarity score between -1 and 1
-     * @throws Error if embeddings have different dimensions
-     */
     cosineSimilarity(a, b) {
         if (a.length !== b.length) {
-            throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}. ` +
-                `Expected ${this.config.dimensions}.`);
+            throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}`);
         }
-        let dotProduct = 0;
-        let normA = 0;
-        let normB = 0;
+        let dotProduct = 0, normA = 0, normB = 0;
         for (let i = 0; i < a.length; i++) {
             dotProduct += a[i] * b[i];
             normA += a[i] * a[i];
@@ -369,85 +144,44 @@ export class HNSWEmbeddingStore {
             return 0;
         return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
     }
-    /**
-     * Check if running in fallback (brute-force) mode.
-     *
-     * @returns true if using brute-force, false if using HNSW
-     */
     isUsingFallback() {
         return !this.hnswEnabled || this.index === null;
     }
-    /**
-     * Close database connections and release resources.
-     *
-     * Saves HNSW index to disk if indexPath was configured.
-     * Safe to call multiple times.
-     */
     close() {
-        // TODO: SMI-1519 - Implement
-        // 1. Save HNSW index if indexPath configured
-        // 2. Close SQLite database
-        // 3. Clear label mappings
         if (this.db) {
             this.db.close();
             this.db = null;
         }
     }
-    // -------------------------------------------------------------------------
-    // Extended Public Methods (HNSW-specific)
-    // -------------------------------------------------------------------------
-    /**
-     * Get statistics about the HNSW index.
-     *
-     * @returns Index statistics including capacity, utilization, and config
-     */
     getStats() {
         let vectorCount = 0;
-        // Get count from SQLite
         if (this.db) {
             const stmt = this.db.prepare('SELECT COUNT(*) as count FROM skill_embeddings');
-            const row = stmt.get();
-            vectorCount = row.count;
+            vectorCount = stmt.get().count;
         }
-        // Get count from VectorDB if available
         if (this.vectorDB) {
             try {
                 const size = this.vectorDB.size();
-                if (!(size instanceof Promise)) {
+                if (!(size instanceof Promise))
                     vectorCount = Math.max(vectorCount, size);
-                }
             }
             catch {
-                // Ignore errors, use SQLite count
+                /* ignore */
             }
         }
-        const utilizationPercent = this.maxElements > 0 ? (vectorCount / this.maxElements) * 100 : 0;
-        // Estimate memory usage (rough approximation)
-        // HNSW uses ~(4 * dimensions + M * 4 * 2) bytes per vector
-        const bytesPerVector = 4 * this.config.dimensions + this.config.m * 8;
-        const memoryUsageBytes = vectorCount * bytesPerVector;
         return {
             vectorCount,
             maxCapacity: this.maxElements,
-            utilizationPercent: Math.round(utilizationPercent * 100) / 100,
+            utilizationPercent: Math.round((vectorCount / this.maxElements) * 10000) / 100,
             m: this.config.m,
             efConstruction: this.config.efConstruction,
             efSearch: this.config.efSearch,
             dimensions: this.config.dimensions,
-            memoryUsageBytes,
+            memoryUsageBytes: estimateMemoryUsage(vectorCount, this.config.dimensions, this.config.m),
             isHNSWEnabled: this.vectorDB !== null,
             indexPath: this.indexPath,
         };
     }
-    /**
-     * Batch insert multiple embeddings efficiently.
-     *
-     * More efficient than calling storeEmbedding() in a loop
-     * due to batched SQLite transactions and HNSW insertions.
-     *
-     * @param embeddings - Array of embeddings to insert
-     * @returns Batch operation result with counts and timing
-     */
     batchInsert(embeddings) {
         const startTime = Date.now();
         const result = {
@@ -462,54 +196,37 @@ export class HNSWEmbeddingStore {
             result.durationMs = Date.now() - startTime;
             return result;
         }
-        // Use a transaction for batch SQLite operations
         const insertStmt = this.db.prepare(`
       INSERT OR REPLACE INTO skill_embeddings (skill_id, embedding, text, created_at)
       VALUES (?, ?, ?, unixepoch())
     `);
-        const checkStmt = this.db.prepare(`
-      SELECT 1 FROM skill_embeddings WHERE skill_id = ?
-    `);
+        const checkStmt = this.db.prepare('SELECT 1 FROM skill_embeddings WHERE skill_id = ?');
         const transaction = this.db.transaction(() => {
             for (const { skillId, embedding, text } of embeddings) {
                 try {
-                    // Validate dimensions
                     if (embedding.length !== this.config.dimensions) {
                         result.failed++;
-                        result.errors.push({
-                            skillId,
-                            error: `Dimension mismatch: got ${embedding.length}, expected ${this.config.dimensions}`,
-                        });
+                        result.errors.push({ skillId, error: `Dimension mismatch: ${embedding.length}` });
                         continue;
                     }
-                    // Check if exists (for updated count)
                     const exists = checkStmt.get(skillId);
-                    // Insert into SQLite
-                    const buffer = Buffer.from(embedding.buffer);
-                    insertStmt.run(skillId, buffer, text);
-                    // Insert into VectorDB
+                    insertStmt.run(skillId, Buffer.from(embedding.buffer), text);
                     if (this.vectorDB) {
                         try {
                             this.vectorDB.insert(embedding, skillId, { text });
                         }
                         catch (err) {
-                            // Log but don't fail - SQLite is the source of truth
-                            console.warn(`[HNSWEmbeddingStore] VectorDB insert failed for ${skillId}: ${err}`);
+                            console.warn(`VectorDB insert failed for ${skillId}: ${err}`);
                         }
                     }
-                    if (exists) {
+                    if (exists)
                         result.updated++;
-                    }
-                    else {
+                    else
                         result.inserted++;
-                    }
                 }
                 catch (err) {
                     result.failed++;
-                    result.errors.push({
-                        skillId,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    result.errors.push({ skillId, error: err instanceof Error ? err.message : String(err) });
                 }
             }
         });
@@ -517,207 +234,106 @@ export class HNSWEmbeddingStore {
         result.durationMs = Date.now() - startTime;
         return result;
     }
-    /**
-     * Remove an embedding from the store.
-     *
-     * Note: HNSW does not support true deletion. The vector is marked
-     * as deleted and excluded from search results, but memory is not
-     * reclaimed until the index is rebuilt.
-     *
-     * @param skillId - Unique identifier for the skill to remove
-     * @returns true if removed, false if not found
-     */
     removeEmbedding(skillId) {
         let removed = false;
-        // Remove from SQLite
         if (this.db) {
             const stmt = this.db.prepare('DELETE FROM skill_embeddings WHERE skill_id = ?');
-            const result = stmt.run(skillId);
-            removed = result.changes > 0;
+            removed = stmt.run(skillId).changes > 0;
         }
-        // Remove from VectorDB (if supported)
         if (this.vectorDB && removed) {
             try {
                 const vdbResult = this.vectorDB.remove(skillId);
-                // VectorDB.remove may be sync or async
                 if (vdbResult instanceof Promise) {
-                    vdbResult.catch((err) => {
-                        console.warn(`[HNSWEmbeddingStore] VectorDB remove failed for ${skillId}: ${err}`);
-                    });
+                    vdbResult.catch((err) => console.warn(`VectorDB remove failed: ${err}`));
                 }
             }
             catch (err) {
-                // Log but don't fail - SQLite is the source of truth
-                console.warn(`[HNSWEmbeddingStore] VectorDB remove failed for ${skillId}: ${err}`);
+                console.warn(`VectorDB remove failed: ${err}`);
             }
         }
         return removed;
     }
-    /**
-     * Save the HNSW index to disk.
-     *
-     * Note: V3 VectorDB manages its own persistence, so this is a no-op
-     * unless using hnswlib-node directly.
-     *
-     * @throws Error if indexPath was not configured
-     */
     saveIndex() {
-        if (!this.indexPath) {
+        if (!this.indexPath)
             throw new Error('Cannot save index: indexPath not configured');
-        }
-        // V3 VectorDB handles its own persistence
-        // For hnswlib-node, we would call index.saveIndex(this.indexPath)
-        console.log(`[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend`);
+        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
     }
-    /**
-     * Load the HNSW index from disk.
-     *
-     * Note: V3 VectorDB manages its own persistence, so this is a no-op
-     * unless using hnswlib-node directly.
-     *
-     * @throws Error if indexPath was not configured or file doesn't exist
-     */
     loadIndex() {
-        if (!this.indexPath) {
+        if (!this.indexPath)
             throw new Error('Cannot load index: indexPath not configured');
-        }
-        // V3 VectorDB handles its own persistence
-        // For hnswlib-node, we would call index.loadIndex(this.indexPath)
-        console.log(`[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend`);
+        console.log('[HNSWEmbeddingStore] Index persistence managed by V3 VectorDB backend');
     }
-    /**
-     * Rebuild the HNSW index from SQLite data.
-     *
-     * Useful after many deletions to reclaim memory, or to apply
-     * new HNSW configuration parameters.
-     *
-     * @param newConfig - Optional new HNSW configuration
-     */
     async rebuildIndex(newConfig) {
-        // Update config if provided
-        if (newConfig) {
+        if (newConfig)
             Object.assign(this.config, newConfig);
-        }
-        // Clear existing VectorDB
         if (this.vectorDB) {
             try {
                 const clearResult = this.vectorDB.clear();
-                if (clearResult instanceof Promise) {
+                if (clearResult instanceof Promise)
                     await clearResult;
-                }
             }
             catch (err) {
-                console.warn(`[HNSWEmbeddingStore] Failed to clear VectorDB: ${err}`);
+                console.warn(`Failed to clear VectorDB: ${err}`);
             }
         }
-        // Reinitialize VectorDB
         await this.initHNSWIndex();
-        // Re-insert all embeddings from SQLite
         if (this.db && this.vectorDB) {
             const allEmbeddings = this.getAllEmbeddings();
             for (const [skillId, embedding] of allEmbeddings) {
                 try {
                     const result = this.vectorDB.insert(embedding, skillId);
-                    if (result instanceof Promise) {
+                    if (result instanceof Promise)
                         await result;
-                    }
                 }
                 catch (err) {
-                    console.warn(`[HNSWEmbeddingStore] Failed to reinsert ${skillId}: ${err}`);
+                    console.warn(`Failed to reinsert ${skillId}: ${err}`);
                 }
             }
         }
     }
-    /**
-     * Update efSearch parameter at runtime.
-     *
-     * Note: V3 VectorDB does not expose efSearch tuning directly.
-     * This method is provided for API compatibility.
-     *
-     * @param efSearch - New efSearch value (must be > 0)
-     */
     setEfSearch(efSearch) {
-        if (efSearch <= 0) {
+        if (efSearch <= 0)
             throw new Error('efSearch must be > 0');
-        }
         this.config.efSearch = efSearch;
-        // V3 VectorDB doesn't expose efSearch tuning
-        // For hnswlib-node, we would call index.setEfSearch(efSearch)
-        console.log(`[HNSWEmbeddingStore] efSearch updated to ${efSearch} (will apply on next search)`);
+        console.log(`[HNSWEmbeddingStore] efSearch updated to ${efSearch}`);
     }
-    // -------------------------------------------------------------------------
-    // Private Methods
-    // -------------------------------------------------------------------------
-    /**
-     * Determine whether to use HNSW based on explicit option or environment.
-     */
-    shouldUseHNSW(explicit) {
-        if (explicit !== undefined) {
-            return explicit;
-        }
-        // Check environment variable
-        const envValue = process.env.SKILLSMITH_USE_HNSW;
-        if (envValue !== undefined) {
-            return envValue === 'true' || envValue === '1';
-        }
-        // Default to false (use brute-force) for backward compatibility
-        // TODO: Consider changing default to true in future version
-        return false;
-    }
-    /**
-     * Initialize SQLite database and create tables.
-     */
+    // Private methods
     initDatabase(dbPath) {
         this.db = new Database(dbPath);
-        // Create skill_embeddings table
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS skill_embeddings (
         skill_id TEXT PRIMARY KEY,
         embedding BLOB NOT NULL,
         text TEXT NOT NULL,
         created_at INTEGER DEFAULT (unixepoch())
-      )
-    `);
-        // Create index for fast lookups
-        this.db.exec(`
-      CREATE INDEX IF NOT EXISTS idx_skill_embeddings_id
-      ON skill_embeddings(skill_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_skill_embeddings_id ON skill_embeddings(skill_id);
     `);
     }
-    /**
-     * Initialize HNSW index using V3 VectorDB API.
-     * Falls back gracefully if V3 is unavailable.
-     */
+    // IMPORTANT: Keep dynamic import here for V3 lazy loading / graceful degradation
     async initHNSWIndex() {
         try {
-            // Dynamically import V3 VectorDB module
             const vectorDbModule = await import('claude-flow/v3/@claude-flow/cli/dist/src/ruvector/vector-db.js');
-            // Load ruvector backend (may use WASM acceleration)
             const loaded = await vectorDbModule.loadRuVector();
-            if (!loaded) {
-                console.warn('[HNSWEmbeddingStore] ruvector not available, using fallback backend');
-            }
-            // Create VectorDB instance
+            if (!loaded)
+                console.warn('[HNSWEmbeddingStore] ruvector not available');
             this.vectorDB = await vectorDbModule.createVectorDB(this.config.dimensions);
-            // Log status
             const status = vectorDbModule.getStatus();
-            console.log(`[HNSWEmbeddingStore] Initialized with backend: ${status.backend}` +
-                (status.wasmAccelerated ? ' (WASM accelerated)' : ''));
-            // Re-populate VectorDB from SQLite if we have existing data
+            console.log(`[HNSWEmbeddingStore] Initialized: ${status.backend}${status.wasmAccelerated ? ' (WASM)' : ''}`);
+            // Rebuild from SQLite
             if (this.db) {
                 const count = this.db.prepare('SELECT COUNT(*) as c FROM skill_embeddings').get();
                 if (count.c > 0) {
-                    console.log(`[HNSWEmbeddingStore] Rebuilding index from ${count.c} existing embeddings...`);
+                    console.log(`[HNSWEmbeddingStore] Rebuilding from ${count.c} embeddings...`);
                     const allEmbeddings = this.getAllEmbeddings();
                     for (const [skillId, embedding] of allEmbeddings) {
                         try {
                             const result = this.vectorDB.insert(embedding, skillId);
-                            if (result instanceof Promise) {
+                            if (result instanceof Promise)
                                 await result;
-                            }
                         }
                         catch (err) {
-                            console.warn(`[HNSWEmbeddingStore] Failed to insert ${skillId}: ${err}`);
+                            console.warn(`Failed to insert ${skillId}: ${err}`);
                         }
                     }
                     console.log(`[HNSWEmbeddingStore] Index rebuilt with ${allEmbeddings.size} vectors`);
@@ -725,81 +341,14 @@ export class HNSWEmbeddingStore {
             }
         }
         catch (err) {
-            // V3 VectorDB not available - will use brute-force fallback
-            console.warn(`[HNSWEmbeddingStore] Failed to initialize V3 VectorDB, using brute-force fallback: ${err}`);
+            console.warn(`[HNSWEmbeddingStore] V3 VectorDB unavailable, using brute-force: ${err}`);
             this.vectorDB = null;
         }
     }
-    /**
-     * Convert HNSW distance to similarity score.
-     * HNSW returns distances, we need similarities (higher = more similar).
-     */
     distanceToSimilarity(distance) {
-        // For cosine space, HNSW returns 1 - cosine_similarity
-        // So similarity = 1 - distance
-        if (this.distanceMetric === 'cosine') {
+        if (this.distanceMetric === 'cosine')
             return 1 - distance;
-        }
-        // For L2/IP, need different conversion
-        // TODO: Implement for other metrics
         return 1 / (1 + distance);
     }
 }
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Create an HNSWEmbeddingStore with a preset configuration.
- *
- * @param preset - Preset name ('small', 'medium', 'large', 'xlarge')
- * @param options - Additional options (merged with preset)
- * @returns Configured HNSWEmbeddingStore instance
- *
- * @example
- * ```typescript
- * const store = createHNSWStore('large', {
- *   dbPath: './embeddings.db',
- *   indexPath: './embeddings.hnsw',
- * });
- * ```
- */
-export function createHNSWStore(preset, options = {}) {
-    return new HNSWEmbeddingStore({
-        ...options,
-        hnswConfig: HNSW_PRESETS[preset],
-    });
-}
-/**
- * Check if hnswlib-node is available.
- *
- * Useful for conditional logic or graceful degradation.
- *
- * @returns true if hnswlib-node can be loaded
- */
-export async function isHNSWAvailable() {
-    try {
-        // Dynamic import to check availability without static analysis errors
-        await Function('return import("hnswlib-node")')();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Dynamically load hnswlib-node module.
- *
- * @returns The HierarchicalNSW constructor, or null if unavailable
- * @internal
- */
-export async function loadHNSWLib() {
-    try {
-        // Dynamic import to avoid TypeScript static analysis
-        const mod = await Function('return import("hnswlib-node")')();
-        return mod;
-    }
-    catch {
-        return null;
-    }
-}
 //# sourceMappingURL=hnsw-store.js.map