agentdb 1.6.0 → 2.0.0-alpha.1

package/dist/backends/hnswlib/HNSWLibBackend.js

@@ -0,0 +1,316 @@
+/**
+ * HNSWLibBackend - Vector backend adapter for hnswlib-node
+ *
+ * Wraps existing HNSWIndex controller to implement VectorBackend interface.
+ * Handles string ID to numeric label mapping required by hnswlib.
+ *
+ * Features:
+ * - String ID support (maps to hnswlib numeric labels)
+ * - Metadata storage alongside vectors
+ * - Persistent save/load with mappings
+ * - Backward compatible with existing HNSWIndex usage
+ *
+ * Note: hnswlib-node doesn't support true deletion - removed IDs are
+ * tracked but vectors remain until rebuild.
+ */
+import hnswlibNode from 'hnswlib-node';
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+const { HierarchicalNSW } = hnswlibNode;
+export class HNSWLibBackend {
+    name = 'hnswlib';
+    index = null;
+    config;
+    // String ID <-> Numeric Label mappings (hnswlib requires numeric labels)
+    idToLabel = new Map();
+    labelToId = new Map();
+    metadata = new Map();
+    nextLabel = 0;
+    // Tracking for deletions (hnswlib doesn't support true deletion)
+    deletedIds = new Set();
+    constructor(config) {
+        this.config = {
+            maxElements: 100000,
+            M: 16,
+            efConstruction: 200,
+            efSearch: 100,
+            ...config,
+        };
+    }
+    /**
+     * Initialize the HNSW index
+     * Must be called after construction
+     */
+    async initialize() {
+        // Map metric names to hnswlib format
+        const metricMap = {
+            cosine: 'cosine',
+            l2: 'l2',
+            ip: 'ip',
+        };
+        const metric = metricMap[this.config.metric] || 'cosine';
+        // Create new HNSW index
+        this.index = new HierarchicalNSW(metric, this.config.dimension);
+        this.index.initIndex(this.config.maxElements, this.config.M, this.config.efConstruction);
+        this.index.setEf(this.config.efSearch);
+        console.log(`[HNSWLibBackend] Initialized with dimension=${this.config.dimension}, ` +
+            `metric=${metric}, M=${this.config.M}, efConstruction=${this.config.efConstruction}`);
+    }
+    /**
+     * Insert a single vector with optional metadata
+     */
+    insert(id, embedding, metadata) {
+        if (!this.index) {
+            throw new Error('Backend not initialized. Call initialize() first.');
+        }
+        // Check if ID already exists
+        if (this.idToLabel.has(id)) {
+            throw new Error(`Vector with ID '${id}' already exists`);
+        }
+        // Allocate numeric label
+        const label = this.nextLabel++;
+        // Add to index (hnswlib requires number[] not Float32Array)
+        this.index.addPoint(Array.from(embedding), label);
+        // Store mappings
+        this.idToLabel.set(id, label);
+        this.labelToId.set(label, id);
+        // Store metadata if provided
+        if (metadata) {
+            this.metadata.set(id, metadata);
+        }
+        // Remove from deleted set if re-inserting
+        this.deletedIds.delete(id);
+    }
+    /**
+     * Insert multiple vectors in batch
+     */
+    insertBatch(items) {
+        for (const item of items) {
+            this.insert(item.id, item.embedding, item.metadata);
+        }
+    }
+    /**
+     * Search for k-nearest neighbors
+     */
+    search(query, k, options) {
+        if (!this.index) {
+            throw new Error('Backend not initialized. Call initialize() first.');
+        }
+        // Update efSearch if specified
+        if (options?.efSearch) {
+            this.index.setEf(options.efSearch);
+        }
+        // Perform HNSW search
+        const result = this.index.searchKnn(Array.from(query), k);
+        const results = [];
+        for (let i = 0; i < result.neighbors.length; i++) {
+            const label = result.neighbors[i];
+            const distance = result.distances[i];
+            // Map label back to ID
+            const id = this.labelToId.get(label);
+            if (!id) {
+                console.warn(`[HNSWLibBackend] Label ${label} not found in mapping`);
+                continue;
+            }
+            // Skip deleted IDs
+            if (this.deletedIds.has(id)) {
+                continue;
+            }
+            // Convert distance to similarity
+            const similarity = this.distanceToSimilarity(distance);
+            // Apply threshold if specified
+            if (options?.threshold !== undefined && similarity < options.threshold) {
+                continue;
+            }
+            results.push({
+                id,
+                distance,
+                similarity,
+                metadata: this.metadata.get(id),
+            });
+        }
+        // Apply metadata filters if specified (post-filtering)
+        if (options?.filter) {
+            return this.applyFilters(results, options.filter);
+        }
+        return results;
+    }
+    /**
+     * Remove a vector by ID
+     * Note: hnswlib doesn't support true deletion - we mark as deleted
+     */
+    remove(id) {
+        const label = this.idToLabel.get(id);
+        if (label === undefined) {
+            return false; // Not found
+        }
+        // Mark as deleted (can't actually remove from hnswlib)
+        this.deletedIds.add(id);
+        this.metadata.delete(id);
+        // Note: We keep idToLabel/labelToId mappings for consistency
+        // A full rebuild would be needed to reclaim space
+        return true;
+    }
+    /**
+     * Get backend statistics
+     */
+    getStats() {
+        const activeCount = this.idToLabel.size - this.deletedIds.size;
+        return {
+            count: activeCount,
+            dimension: this.config.dimension,
+            metric: this.config.metric,
+            backend: 'hnswlib',
+            memoryUsage: 0, // hnswlib doesn't expose memory usage
+        };
+    }
+    /**
+     * Save index to disk with mappings
+     */
+    async save(savePath) {
+        if (!this.index) {
+            throw new Error('No index to save');
+        }
+        try {
+            // Create directory if needed
+            const indexDir = path.dirname(savePath);
+            if (!fsSync.existsSync(indexDir)) {
+                await fs.mkdir(indexDir, { recursive: true });
+            }
+            // Save HNSW index
+            this.index.writeIndex(savePath);
+            // Save mappings and metadata
+            const mappingsPath = savePath + '.mappings.json';
+            const mappings = {
+                idToLabel: Object.fromEntries(this.idToLabel.entries()),
+                labelToId: Object.fromEntries(Array.from(this.labelToId.entries()).map(([k, v]) => [k.toString(), v])),
+                metadata: Object.fromEntries(this.metadata.entries()),
+                nextLabel: this.nextLabel,
+                config: this.config,
+            };
+            await fs.writeFile(mappingsPath, JSON.stringify(mappings, null, 2));
+            console.log(`[HNSWLibBackend] Index saved to ${savePath}`);
+            console.log(`[HNSWLibBackend] Mappings saved to ${mappingsPath}`);
+        }
+        catch (error) {
+            console.error('[HNSWLibBackend] Failed to save index:', error);
+            throw error;
+        }
+    }
+    /**
+     * Load index from disk with mappings
+     */
+    async load(loadPath) {
+        if (!fsSync.existsSync(loadPath)) {
+            throw new Error(`Index file not found: ${loadPath}`);
+        }
+        try {
+            console.log(`[HNSWLibBackend] Loading index from ${loadPath}...`);
+            // Initialize index first
+            const metricMap = {
+                cosine: 'cosine',
+                l2: 'l2',
+                ip: 'ip',
+            };
+            const metric = metricMap[this.config.metric] || 'cosine';
+            this.index = new HierarchicalNSW(metric, this.config.dimension);
+            // Load HNSW index
+            this.index.readIndex(loadPath);
+            this.index.setEf(this.config.efSearch);
+            // Load mappings and metadata
+            const mappingsPath = loadPath + '.mappings.json';
+            if (fsSync.existsSync(mappingsPath)) {
+                const mappingsData = JSON.parse(await fs.readFile(mappingsPath, 'utf-8'));
+                // Restore mappings
+                this.idToLabel = new Map(Object.entries(mappingsData.idToLabel));
+                this.labelToId = new Map(Object.entries(mappingsData.labelToId).map(([k, v]) => [Number(k), v]));
+                this.metadata = new Map(Object.entries(mappingsData.metadata || {}));
+                this.nextLabel = mappingsData.nextLabel;
+                // Update config if saved
+                if (mappingsData.config) {
+                    this.config = { ...this.config, ...mappingsData.config };
+                }
+                console.log(`[HNSWLibBackend] ✅ Index loaded successfully (${this.idToLabel.size} vectors)`);
+            }
+            else {
+                console.warn('[HNSWLibBackend] No mappings file found - index loaded without ID mappings');
+            }
+        }
+        catch (error) {
+            console.error('[HNSWLibBackend] Failed to load index:', error);
+            this.index = null;
+            throw error;
+        }
+    }
+    /**
+     * Close and cleanup resources
+     */
+    close() {
+        this.index = null;
+        this.idToLabel.clear();
+        this.labelToId.clear();
+        this.metadata.clear();
+        this.deletedIds.clear();
+        this.nextLabel = 0;
+    }
+    /**
+     * Convert distance to similarity based on metric
+     * Maps to [0, 1] range where 1 = most similar
+     */
+    distanceToSimilarity(distance) {
+        switch (this.config.metric) {
+            case 'cosine':
+                // Cosine distance is 1 - similarity, so invert
+                return 1 - distance;
+            case 'l2':
+                // Euclidean distance: use exponential decay
+                return Math.exp(-distance);
+            case 'ip':
+                // Inner product: negate distance (higher IP = more similar)
+                return -distance;
+            default:
+                return 1 - distance;
+        }
+    }
+    /**
+     * Apply metadata filters (post-filtering)
+     */
+    applyFilters(results, filters) {
+        return results.filter((result) => {
+            if (!result.metadata)
+                return false;
+            // Check if all filter conditions match
+            return Object.entries(filters).every(([key, value]) => {
+                return result.metadata[key] === value;
+            });
+        });
+    }
+    /**
+     * Check if needs rebuilding (for backward compat with HNSWIndex)
+     * @param updateThreshold - Percentage of deletes to trigger rebuild (default: 0.1)
+     */
+    needsRebuild(updateThreshold = 0.1) {
+        if (this.idToLabel.size === 0)
+            return false;
+        const deletePercentage = this.deletedIds.size / this.idToLabel.size;
+        return deletePercentage > updateThreshold;
+    }
+    /**
+     * Update efSearch parameter
+     */
+    setEfSearch(ef) {
+        if (this.index) {
+            this.index.setEf(ef);
+            this.config.efSearch = ef;
+            console.log(`[HNSWLibBackend] efSearch updated to ${ef}`);
+        }
+    }
+    /**
+     * Check if backend is ready
+     */
+    isReady() {
+        return this.index !== null;
+    }
+}
+//# sourceMappingURL=HNSWLibBackend.js.map

package/dist/backends/hnswlib/HNSWLibBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HNSWLibBackend.js","sourceRoot":"","sources":["../../../src/backends/hnswlib/HNSWLibBackend.ts"],"names":[],"mappings":"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"}

package/dist/backends/hnswlib/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HNSWLib Backend Exports
+ *
+ * Export HNSWLibBackend adapter for hnswlib-node integration
+ */
+export { HNSWLibBackend } from './HNSWLibBackend.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/hnswlib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/hnswlib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/backends/hnswlib/index.js

@@ -0,0 +1,7 @@
+/**
+ * HNSWLib Backend Exports
+ *
+ * Export HNSWLibBackend adapter for hnswlib-node integration
+ */
+export { HNSWLibBackend } from './HNSWLibBackend.js';
+//# sourceMappingURL=index.js.map

package/dist/backends/hnswlib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/backends/hnswlib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/backends/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AgentDB Backends - Unified Vector Storage Interface
+ *
+ * Provides automatic backend selection between RuVector and HNSWLib
+ * with graceful fallback and clear error messages.
+ */
+export type { VectorBackend, VectorConfig, SearchResult, SearchOptions, VectorStats } from './VectorBackend.js';
+export { RuVectorBackend } from './ruvector/RuVectorBackend.js';
+export { RuVectorLearning } from './ruvector/RuVectorLearning.js';
+export { HNSWLibBackend } from './hnswlib/HNSWLibBackend.js';
+export { createBackend, detectBackends, getRecommendedBackend, isBackendAvailable, getInstallCommand } from './factory.js';
+export type { BackendType, BackendDetection } from './factory.js';
+export type { LearningConfig, EnhancementOptions } from './ruvector/RuVectorLearning.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D,OAAO,EACL,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/backends/index.js

@@ -0,0 +1,13 @@
+/**
+ * AgentDB Backends - Unified Vector Storage Interface
+ *
+ * Provides automatic backend selection between RuVector and HNSWLib
+ * with graceful fallback and clear error messages.
+ */
+// Backend implementations
+export { RuVectorBackend } from './ruvector/RuVectorBackend.js';
+export { RuVectorLearning } from './ruvector/RuVectorLearning.js';
+export { HNSWLibBackend } from './hnswlib/HNSWLibBackend.js';
+// Factory and detection
+export { createBackend, detectBackends, getRecommendedBackend, isBackendAvailable, getInstallCommand } from './factory.js';
+//# sourceMappingURL=index.js.map

package/dist/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,wBAAwB;AACxB,OAAO,EACL,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,cAAc,CAAC"}

package/dist/backends/ruvector/RuVectorBackend.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RuVectorBackend - High-Performance Vector Storage
+ *
+ * Implements VectorBackend using @ruvector/core with optional GNN support.
+ * Provides <100µs search latency with native SIMD optimizations.
+ *
+ * Features:
+ * - Automatic fallback when @ruvector packages not installed
+ * - Separate metadata storage for rich queries
+ * - Distance-to-similarity conversion for all metrics
+ * - Batch operations for optimal throughput
+ * - Persistent storage with separate metadata files
+ */
+import type { VectorBackend, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';
+export declare class RuVectorBackend implements VectorBackend {
+    readonly name: "ruvector";
+    private db;
+    private config;
+    private metadata;
+    private initialized;
+    constructor(config: VectorConfig);
+    /**
+     * Initialize RuVector database with optional dependency handling
+     */
+    initialize(): Promise<void>;
+    /**
+     * Insert single vector with optional metadata
+     */
+    insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;
+    /**
+     * Batch insert for optimal performance
+     */
+    insertBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, any>;
+    }>): void;
+    /**
+     * Search for k-nearest neighbors with optional filtering
+     */
+    search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
+    /**
+     * Remove vector by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Get database statistics
+     */
+    getStats(): VectorStats;
+    /**
+     * Save index and metadata to disk
+     */
+    save(path: string): Promise<void>;
+    /**
+     * Load index and metadata from disk
+     */
+    load(path: string): Promise<void>;
+    /**
+     * Close and cleanup resources
+     */
+    close(): void;
+    /**
+     * Convert distance to similarity score based on metric
+     *
+     * Cosine: distance is already in [0, 2], where 0 = identical
+     * L2: exponential decay for unbounded distances
+     * IP: negative inner product, so negate for similarity
+     */
+    private distanceToSimilarity;
+    /**
+     * Ensure database is initialized before operations
+     */
+    private ensureInitialized;
+}
+//# sourceMappingURL=RuVectorBackend.d.ts.map

package/dist/backends/ruvector/RuVectorBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuVectorBackend.d.ts","sourceRoot":"","sources":["../../../src/backends/ruvector/RuVectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEjH,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,YAAY;IAIhC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCjC;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAWjF;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,GAAG,IAAI;IAQxG;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE;IAoC/E;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAY3B;;OAEG;IACH,QAAQ,IAAI,WAAW;IAYvB;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevC;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}

package/dist/backends/ruvector/RuVectorBackend.js

@@ -0,0 +1,198 @@
+/**
+ * RuVectorBackend - High-Performance Vector Storage
+ *
+ * Implements VectorBackend using @ruvector/core with optional GNN support.
+ * Provides <100µs search latency with native SIMD optimizations.
+ *
+ * Features:
+ * - Automatic fallback when @ruvector packages not installed
+ * - Separate metadata storage for rich queries
+ * - Distance-to-similarity conversion for all metrics
+ * - Batch operations for optimal throughput
+ * - Persistent storage with separate metadata files
+ */
+export class RuVectorBackend {
+    name = 'ruvector';
+    db; // VectorDB from @ruvector/core
+    config;
+    metadata = new Map();
+    initialized = false;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Initialize RuVector database with optional dependency handling
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            // Try main ruvector package first (includes core, gnn, graph)
+            let VectorDB;
+            try {
+                const ruvector = await import('ruvector');
+                VectorDB = ruvector.VectorDB || ruvector.default?.VectorDB;
+            }
+            catch {
+                // Fallback to @ruvector/core for backward compatibility
+                const core = await import('@ruvector/core');
+                VectorDB = core.VectorDB || core.default;
+            }
+            this.db = new VectorDB(this.config.dimension, {
+                metric: this.config.metric,
+                maxElements: this.config.maxElements || 100000,
+                efConstruction: this.config.efConstruction || 200,
+                M: this.config.M || 16
+            });
+            this.initialized = true;
+        }
+        catch (error) {
+            throw new Error(`RuVector initialization failed. Please install: npm install ruvector\n` +
+                `Or legacy packages: npm install @ruvector/core\n` +
+                `Error: ${error.message}`);
+        }
+    }
+    /**
+     * Insert single vector with optional metadata
+     */
+    insert(id, embedding, metadata) {
+        this.ensureInitialized();
+        // RuVector expects regular arrays
+        this.db.insert(id, Array.from(embedding));
+        if (metadata) {
+            this.metadata.set(id, metadata);
+        }
+    }
+    /**
+     * Batch insert for optimal performance
+     */
+    insertBatch(items) {
+        this.ensureInitialized();
+        for (const item of items) {
+            this.insert(item.id, item.embedding, item.metadata);
+        }
+    }
+    /**
+     * Search for k-nearest neighbors with optional filtering
+     */
+    search(query, k, options) {
+        this.ensureInitialized();
+        // Apply efSearch parameter if provided
+        if (options?.efSearch) {
+            this.db.setEfSearch(options.efSearch);
+        }
+        // Perform vector search
+        const results = this.db.search(Array.from(query), k);
+        // Convert results and apply filtering
+        return results
+            .map((r) => ({
+            id: r.id,
+            distance: r.distance,
+            similarity: this.distanceToSimilarity(r.distance),
+            metadata: this.metadata.get(r.id)
+        }))
+            .filter((r) => {
+            // Apply similarity threshold
+            if (options?.threshold && r.similarity < options.threshold) {
+                return false;
+            }
+            // Apply metadata filters
+            if (options?.filter && r.metadata) {
+                return Object.entries(options.filter).every(([key, value]) => r.metadata[key] === value);
+            }
+            return true;
+        });
+    }
+    /**
+     * Remove vector by ID
+     */
+    remove(id) {
+        this.ensureInitialized();
+        this.metadata.delete(id);
+        try {
+            return this.db.remove(id);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get database statistics
+     */
+    getStats() {
+        this.ensureInitialized();
+        return {
+            count: this.db.count(),
+            dimension: this.config.dimension,
+            metric: this.config.metric,
+            backend: 'ruvector',
+            memoryUsage: this.db.memoryUsage?.() || 0
+        };
+    }
+    /**
+     * Save index and metadata to disk
+     */
+    async save(path) {
+        this.ensureInitialized();
+        // Save vector index
+        this.db.save(path);
+        // Save metadata separately as JSON
+        const metadataPath = path + '.meta.json';
+        const fs = await import('fs/promises');
+        await fs.writeFile(metadataPath, JSON.stringify(Object.fromEntries(this.metadata), null, 2));
+    }
+    /**
+     * Load index and metadata from disk
+     */
+    async load(path) {
+        this.ensureInitialized();
+        // Load vector index
+        this.db.load(path);
+        // Load metadata
+        const metadataPath = path + '.meta.json';
+        try {
+            const fs = await import('fs/promises');
+            const data = await fs.readFile(metadataPath, 'utf-8');
+            this.metadata = new Map(Object.entries(JSON.parse(data)));
+        }
+        catch {
+            // No metadata file - this is okay for backward compatibility
+            console.debug(`[RuVectorBackend] No metadata file found at ${metadataPath}`);
+        }
+    }
+    /**
+     * Close and cleanup resources
+     */
+    close() {
+        // RuVector cleanup if needed
+        this.metadata.clear();
+    }
+    /**
+     * Convert distance to similarity score based on metric
+     *
+     * Cosine: distance is already in [0, 2], where 0 = identical
+     * L2: exponential decay for unbounded distances
+     * IP: negative inner product, so negate for similarity
+     */
+    distanceToSimilarity(distance) {
+        switch (this.config.metric) {
+            case 'cosine':
+                return 1 - distance; // cosine distance is 1 - similarity
+            case 'l2':
+                return Math.exp(-distance); // exponential decay
+            case 'ip':
+                return -distance; // inner product: higher is better
+            default:
+                return 1 - distance;
+        }
+    }
+    /**
+     * Ensure database is initialized before operations
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('RuVectorBackend not initialized. Call initialize() first.');
+        }
+    }
+}
+//# sourceMappingURL=RuVectorBackend.js.map