@henrychong-ai/mcp-neo4j-knowledge-graph 1.0.0

package/dist/storage/SearchResultCache.js

@@ -0,0 +1,258 @@
+/**
+ * Cache system for search results to improve performance for repeated queries
+ */
+/**
+ * A memory-efficient cache for search results
+ */
+export class SearchResultCache {
+    /**
+     * Create a new SearchResultCache
+     * @param config Configuration options
+     */
+    constructor(config) {
+        this.cache = new Map();
+        this.currentSize = 0;
+        // Statistics
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+        this.totalLookupTime = 0;
+        this.totalLookups = 0;
+        // Default to 100MB max size
+        this.maxSize = config?.maxSize || 100 * 1024 * 1024;
+        // Default to 5 minute TTL
+        this.defaultTtl = config?.defaultTtl || 5 * 60 * 1000;
+        // Enable stats by default
+        this.enableStats = config?.enableStats !== false;
+    }
+    /**
+     * Estimate the size of an object in bytes
+     * @param obj The object to measure
+     * @returns Approximate size in bytes
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    estimateSize(obj) {
+        if (obj === null || obj === undefined) {
+            return 0;
+        }
+        // For arrays of numbers (vectors), use more precise calculation
+        if (Array.isArray(obj) && obj.length > 0 && typeof obj[0] === 'number') {
+            return obj.length * 8; // 8 bytes per number (Float64)
+        }
+        // For strings, use character count * 2 (for UTF-16)
+        if (typeof obj === 'string') {
+            return obj.length * 2;
+        }
+        // For simple objects with a 'data' property containing a string
+        if (obj && typeof obj === 'object' && typeof obj.data === 'string') {
+            return obj.data.length * 2 + 100; // String length + overhead
+        }
+        // Use JSON stringification as an approximation for complex objects
+        // Add a small overhead to account for object structure
+        try {
+            const json = JSON.stringify(obj);
+            return json ? json.length * 2 + 100 : 100; // UTF-16 characters + overhead
+        }
+        catch {
+            // If stringification fails, use a reasonable default
+            return 1024; // 1KB default
+        }
+    }
+    /**
+     * Generate a cache key from a query and parameters
+     * @param query Original query string
+     * @param params Optional parameters that affect the query
+     * @returns A cache key string
+     */
+    generateKey(query, params) {
+        if (!params) {
+            return query;
+        }
+        // Sort keys for consistent key generation regardless of parameter order
+        const sortedParams = Object.keys(params)
+            .sort()
+            .map((key) => `${key}:${JSON.stringify(params[key])}`)
+            .join(',');
+        return `${query}|${sortedParams}`;
+    }
+    /**
+     * Evict the oldest or least valuable entries to free up space
+     * @param requiredSpace The amount of space needed
+     */
+    evictEntries(requiredSpace) {
+        // If cache is empty, nothing to evict
+        if (this.cache.size === 0) {
+            return;
+        }
+        // Create an array of entries sorted by "value"
+        // Value is determined by how recently they were created
+        const entries = Array.from(this.cache.entries()).sort((a, b) => a[1].created - b[1].created);
+        let freedSpace = 0;
+        let evictionCount = 0;
+        // Evict entries until we have enough space
+        for (const [key, entry] of entries) {
+            if (freedSpace >= requiredSpace && evictionCount > 0) {
+                break;
+            }
+            this.cache.delete(key);
+            freedSpace += entry.size;
+            this.currentSize -= entry.size;
+            evictionCount++;
+            // Only evict the oldest entry and then check if we have enough space
+            if (evictionCount === 1 && freedSpace >= requiredSpace) {
+                break;
+            }
+        }
+        // Update statistics
+        if (this.enableStats) {
+            this.evictions += evictionCount;
+        }
+    }
+    /**
+     * Set a cache entry
+     * @param query The original query
+     * @param params Optional parameters that affect the results
+     * @param data The data to cache
+     * @param ttl Optional time-to-live in milliseconds
+     */
+    set(query, data, params, ttl) {
+        // Clean expired entries
+        this.removeExpired();
+        // Generate cache key
+        const key = this.generateKey(query, params);
+        // Estimate data size
+        const size = this.estimateSize(data);
+        // If item is too large for the cache, don't cache it
+        if (size > this.maxSize) {
+            return;
+        }
+        // Calculate expiration time
+        const now = Date.now();
+        const expiration = now + (ttl || this.defaultTtl);
+        // Create cache entry
+        const entry = {
+            data,
+            expiration,
+            created: now,
+            size,
+        };
+        // Check if we need to make space
+        if (this.currentSize + size > this.maxSize) {
+            this.evictEntries(size);
+        }
+        // Add to cache
+        this.cache.set(key, entry);
+        this.currentSize += size;
+    }
+    /**
+     * Get a value from the cache
+     * @param query The original query
+     * @param params Optional parameters that affect the results
+     * @returns The cached data or undefined if not found or expired
+     */
+    get(query, params) {
+        const startTime = this.enableStats ? performance.now() : 0;
+        // Generate cache key
+        const key = this.generateKey(query, params);
+        // Get entry
+        const entry = this.cache.get(key);
+        // Track lookup time
+        if (this.enableStats) {
+            const endTime = performance.now();
+            this.totalLookupTime += endTime - startTime;
+            this.totalLookups++;
+        }
+        // If entry doesn't exist, return undefined
+        if (!entry) {
+            if (this.enableStats) {
+                this.misses++;
+            }
+            return undefined;
+        }
+        // Check if expired
+        if (entry.expiration < Date.now()) {
+            // Remove expired entry
+            this.cache.delete(key);
+            this.currentSize -= entry.size;
+            if (this.enableStats) {
+                this.misses++;
+            }
+            return undefined;
+        }
+        // Valid cache hit
+        if (this.enableStats) {
+            this.hits++;
+        }
+        return entry.data;
+    }
+    /**
+     * Remove all expired entries from the cache
+     */
+    removeExpired() {
+        const now = Date.now();
+        let removedSize = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiration < now) {
+                this.cache.delete(key);
+                removedSize += entry.size;
+            }
+        }
+        this.currentSize -= removedSize;
+    }
+    /**
+     * Clear the entire cache
+     */
+    clear() {
+        this.cache.clear();
+        this.currentSize = 0;
+    }
+    /**
+     * Get cache statistics
+     * @returns Cache statistics
+     */
+    getStats() {
+        // Calculate hit rate
+        const totalRequests = this.hits + this.misses;
+        const hitRate = totalRequests > 0 ? this.hits / totalRequests : 0;
+        // Calculate average lookup time
+        const averageLookupTime = this.totalLookups > 0 ? this.totalLookupTime / this.totalLookups : 0;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            hitRate,
+            currentSize: this.currentSize,
+            maxSize: this.maxSize,
+            entryCount: this.cache.size,
+            evictions: this.evictions,
+            averageLookupTime,
+        };
+    }
+    /**
+     * Get the current number of entries in the cache
+     * @returns Number of entries
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if the cache contains a specific key
+     * @param query The original query
+     * @param params Optional parameters that affect the results
+     * @returns True if the key exists and is not expired
+     */
+    has(query, params) {
+        const key = this.generateKey(query, params);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (entry.expiration < Date.now()) {
+            // Remove expired entry
+            this.cache.delete(key);
+            this.currentSize -= entry.size;
+            return false;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=SearchResultCache.js.map

package/dist/storage/SearchResultCache.js.map

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

package/dist/storage/StorageProvider.d.ts

@@ -0,0 +1,171 @@
+import type { KnowledgeGraph } from '../KnowledgeGraphManager.js';
+import type { Relation } from '../types/relation.js';
+import type { EntityEmbedding, SemanticSearchOptions } from '../types/entity-embedding.js';
+/**
+ * Options for searching nodes in the knowledge graph
+ */
+export interface SearchOptions {
+    /**
+     * Maximum number of results to return
+     */
+    limit?: number;
+    /**
+     * Whether the search should be case-sensitive
+     */
+    caseSensitive?: boolean;
+    /**
+     * Filter results by entity types
+     */
+    entityTypes?: string[];
+}
+/**
+ * Interface for storage providers that can load and save knowledge graphs
+ */
+export interface StorageProvider {
+    /**
+     * Load a knowledge graph from storage
+     * @returns Promise resolving to the loaded knowledge graph
+     */
+    loadGraph(): Promise<KnowledgeGraph>;
+    /**
+     * Save a knowledge graph to storage
+     * @param graph The knowledge graph to save
+     * @returns Promise that resolves when the save is complete
+     */
+    saveGraph(graph: KnowledgeGraph): Promise<void>;
+    /**
+     * Search for nodes in the graph that match the query
+     * @param query The search query string
+     * @param options Optional search parameters
+     * @returns Promise resolving to a KnowledgeGraph containing matching nodes
+     */
+    searchNodes(query: string, options?: SearchOptions): Promise<KnowledgeGraph>;
+    /**
+     * Open specific nodes by their exact names
+     * @param names Array of node names to open
+     * @returns Promise resolving to a KnowledgeGraph containing the specified nodes
+     */
+    openNodes(names: string[]): Promise<KnowledgeGraph>;
+    /**
+     * Create new entities in the knowledge graph
+     * @param entities Array of entities to create
+     * @returns Promise resolving to array of newly created entities with temporal metadata
+     */
+    createEntities(entities: any[]): Promise<any[]>;
+    /**
+     * Create new relations between entities
+     * @param relations Array of relations to create
+     * @returns Promise resolving to array of newly created relations
+     */
+    createRelations(relations: Relation[]): Promise<Relation[]>;
+    /**
+     * Add observations to entities
+     * @param observations Array of objects with entity name and observation contents
+     * @returns Promise resolving to array of objects with entity name and added observations
+     */
+    addObservations(observations: {
+        entityName: string;
+        contents: string[];
+    }[]): Promise<{
+        entityName: string;
+        addedObservations: string[];
+    }[]>;
+    /**
+     * Delete entities and their relations
+     * @param entityNames Array of entity names to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    deleteEntities(entityNames: string[]): Promise<void>;
+    /**
+     * Delete observations from entities
+     * @param deletions Array of objects with entity name and observations to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    deleteObservations(deletions: {
+        entityName: string;
+        observations: string[];
+    }[]): Promise<void>;
+    /**
+     * Delete relations from the graph
+     * @param relations Array of relations to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    deleteRelations(relations: Relation[]): Promise<void>;
+    /**
+     * Get a specific relation by its source, target, and type
+     * @param from Source entity name
+     * @param to Target entity name
+     * @param type Relation type
+     * @returns Promise resolving to the relation or null if not found
+     */
+    getRelation?(from: string, to: string, type: string): Promise<Relation | null>;
+    /**
+     * Update an existing relation with new properties
+     * @param relation The relation with updated properties
+     * @returns Promise that resolves when the update is complete
+     */
+    updateRelation?(relation: Relation): Promise<void>;
+    /**
+     * Get the history of all versions of an entity
+     * @param entityName The name of the entity to retrieve history for
+     * @returns Promise resolving to an array of entity versions in chronological order
+     */
+    getEntityHistory?(entityName: string): Promise<any[]>;
+    /**
+     * Get the history of all versions of a relation
+     * @param from Source entity name
+     * @param to Target entity name
+     * @param relationType Type of the relation
+     * @returns Promise resolving to an array of relation versions in chronological order
+     */
+    getRelationHistory?(from: string, to: string, relationType: string): Promise<any[]>;
+    /**
+     * Get the state of the knowledge graph at a specific point in time
+     * @param timestamp The timestamp to get the graph state at
+     * @returns Promise resolving to the knowledge graph as it was at the specified time
+     */
+    getGraphAtTime?(timestamp: number): Promise<KnowledgeGraph>;
+    /**
+     * Get the current knowledge graph with confidence decay applied to relations
+     * based on their age and the configured decay settings
+     * @returns Promise resolving to the knowledge graph with decayed confidence values
+     */
+    getDecayedGraph?(): Promise<KnowledgeGraph>;
+    /**
+     * Store or update the embedding vector for an entity
+     * @param entityName The name of the entity to update
+     * @param embedding The embedding data to store
+     * @returns Promise that resolves when the update is complete
+     */
+    updateEntityEmbedding?(entityName: string, embedding: EntityEmbedding): Promise<void>;
+    /**
+     * Find entities similar to a query vector
+     * @param queryVector The vector to compare against
+     * @param limit Maximum number of results to return
+     * @returns Promise resolving to array of entities with similarity scores
+     */
+    findSimilarEntities?(queryVector: number[], limit?: number): Promise<any[]>;
+    /**
+     * Search for entities using semantic search
+     * @param query The search query text
+     * @param options Search options including semantic search parameters
+     * @returns Promise resolving to a KnowledgeGraph containing matching entities
+     */
+    semanticSearch?(query: string, options?: SearchOptions & SemanticSearchOptions): Promise<KnowledgeGraph>;
+    /**
+     * Get an entity by name
+     * @param entityName Name of the entity to retrieve
+     * @returns Promise resolving to the entity or null if not found
+     */
+    getEntity(entityName: string): Promise<any | null>;
+}
+export declare namespace StorageProvider {
+    function isStorageProvider(obj: any): boolean;
+}
+/**
+ * Validator class for StorageProvider interface
+ * This exists to ensure there's a concrete export for JavaScript tests
+ */
+export declare class StorageProviderValidator {
+    static isStorageProvider(obj: any): boolean;
+}

package/dist/storage/StorageProvider.js

@@ -0,0 +1,46 @@
+// Add static methods to the StorageProvider interface for JavaScript tests
+// This allows tests to access validation methods directly from the interface
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var StorageProvider;
+(function (StorageProvider) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function isStorageProvider(obj) {
+        return StorageProviderValidator.isStorageProvider(obj);
+    }
+    StorageProvider.isStorageProvider = isStorageProvider;
+})(StorageProvider || (StorageProvider = {}));
+/**
+ * Validator class for StorageProvider interface
+ * This exists to ensure there's a concrete export for JavaScript tests
+ */
+export class StorageProviderValidator {
+    // No implementation - this is just to ensure the symbol exists in the compiled JS
+    // JavaScript tests will use this as a type reference
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static isStorageProvider(obj) {
+        const hasRequiredMethods = obj &&
+            typeof obj.loadGraph === 'function' &&
+            typeof obj.saveGraph === 'function' &&
+            typeof obj.searchNodes === 'function' &&
+            typeof obj.openNodes === 'function' &&
+            typeof obj.createEntities === 'function' &&
+            typeof obj.createRelations === 'function' &&
+            typeof obj.addObservations === 'function' &&
+            typeof obj.deleteEntities === 'function' &&
+            typeof obj.deleteObservations === 'function' &&
+            typeof obj.deleteRelations === 'function' &&
+            typeof obj.getEntity === 'function';
+        // Check that any optional methods, if present, are functions
+        const optionalMethodsValid = (!obj.getRelation || typeof obj.getRelation === 'function') &&
+            (!obj.updateRelation || typeof obj.updateRelation === 'function') &&
+            (!obj.getEntityHistory || typeof obj.getEntityHistory === 'function') &&
+            (!obj.getRelationHistory || typeof obj.getRelationHistory === 'function') &&
+            (!obj.getGraphAtTime || typeof obj.getGraphAtTime === 'function') &&
+            (!obj.getDecayedGraph || typeof obj.getDecayedGraph === 'function') &&
+            (!obj.updateEntityEmbedding || typeof obj.updateEntityEmbedding === 'function') &&
+            (!obj.findSimilarEntities || typeof obj.findSimilarEntities === 'function') &&
+            (!obj.semanticSearch || typeof obj.semanticSearch === 'function');
+        return hasRequiredMethods && optionalMethodsValid;
+    }
+}
+//# sourceMappingURL=StorageProvider.js.map

package/dist/storage/StorageProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageProvider.js","sourceRoot":"","sources":["../../src/storage/StorageProvider.ts"],"names":[],"mappings":"AA0LA,2EAA2E;AAC3E,6EAA6E;AAC7E,2DAA2D;AAC3D,MAAM,KAAW,eAAe,CAK/B;AALD,WAAiB,eAAe;IAC9B,8DAA8D;IAC9D,SAAgB,iBAAiB,CAAC,GAAQ;QACxC,OAAO,wBAAwB,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzD,CAAC;IAFe,iCAAiB,oBAEhC,CAAA;AACH,CAAC,EALgB,eAAe,KAAf,eAAe,QAK/B;AAED;;;GAGG;AACH,MAAM,OAAO,wBAAwB;IACnC,kFAAkF;IAClF,qDAAqD;IACrD,8DAA8D;IAC9D,MAAM,CAAC,iBAAiB,CAAC,GAAQ;QAC/B,MAAM,kBAAkB,GACtB,GAAG;YACH,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU;YACrC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;YACnC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU;YACxC,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU;YAC5C,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YACzC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC;QAEtC,6DAA6D;QAC7D,MAAM,oBAAoB,GACxB,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU,CAAC;YAC3D,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,CAAC;YACrE,CAAC,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU,CAAC;YACzE,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC;YACjE,CAAC,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU,CAAC;YACnE,CAAC,CAAC,GAAG,CAAC,qBAAqB,IAAI,OAAO,GAAG,CAAC,qBAAqB,KAAK,UAAU,CAAC;YAC/E,CAAC,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,UAAU,CAAC;YAC3E,CAAC,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,CAAC,CAAC;QAEpE,OAAO,kBAAkB,IAAI,oBAAoB,CAAC;IACpD,CAAC;CACF"}

package/dist/storage/StorageProviderFactory.d.ts

@@ -0,0 +1,63 @@
+import type { StorageProvider } from './StorageProvider.js';
+import type { VectorStoreFactoryOptions } from './VectorStoreFactory.js';
+export interface StorageProviderConfig {
+    type: 'file' | 'neo4j';
+    options?: {
+        memoryFilePath?: string;
+        enableDecay?: boolean;
+        decayConfig?: {
+            enabled?: boolean;
+            halfLifeDays?: number;
+            minConfidence?: number;
+        };
+        neo4jUri?: string;
+        neo4jUsername?: string;
+        neo4jPassword?: string;
+        neo4jDatabase?: string;
+        neo4jVectorIndexName?: string;
+        neo4jVectorDimensions?: number;
+        neo4jSimilarityFunction?: 'cosine' | 'euclidean';
+    };
+    vectorStoreOptions?: VectorStoreFactoryOptions;
+}
+interface CleanableProvider extends StorageProvider {
+    cleanup?: () => Promise<void>;
+}
+/**
+ * Factory for creating storage providers
+ */
+export declare class StorageProviderFactory {
+    private connectedProviders;
+    /**
+     * Create a storage provider based on configuration
+     * @param config Configuration for the provider
+     * @returns A storage provider instance
+     */
+    createProvider(config: StorageProviderConfig): StorageProvider;
+    /**
+     * Get a default storage provider (Neo4j-based)
+     * @returns A default Neo4jStorageProvider instance
+     */
+    getDefaultProvider(): StorageProvider;
+    /**
+     * Check if a provider is connected
+     * @param provider The provider to check
+     * @returns True if the provider is connected, false otherwise
+     */
+    isProviderConnected(provider: StorageProvider): boolean;
+    /**
+     * Disconnect a provider
+     * @param provider The provider to disconnect
+     */
+    disconnectProvider(provider: StorageProvider): void;
+    /**
+     * Cleanup provider resources and disconnect
+     * @param provider The provider to cleanup
+     */
+    cleanupProvider(provider: CleanableProvider): Promise<void>;
+    /**
+     * Cleanup all connected providers
+     */
+    cleanupAllProviders(): Promise<void>;
+}
+export {};

package/dist/storage/StorageProviderFactory.js

@@ -0,0 +1,113 @@
+import { FileStorageProvider } from './FileStorageProvider.js';
+import { Neo4jStorageProvider } from './neo4j/Neo4jStorageProvider.js';
+/**
+ * Factory for creating storage providers
+ */
+export class StorageProviderFactory {
+    constructor() {
+        // Track connected providers
+        this.connectedProviders = new Set();
+    }
+    /**
+     * Create a storage provider based on configuration
+     * @param config Configuration for the provider
+     * @returns A storage provider instance
+     */
+    createProvider(config) {
+        if (!config) {
+            throw new Error('Storage provider configuration is required');
+        }
+        if (!config.type) {
+            throw new Error('Storage provider type is required');
+        }
+        if (!config.options) {
+            throw new Error('Storage provider options are required');
+        }
+        let provider;
+        switch (config.type.toLowerCase()) {
+            case 'file': {
+                if (!config.options.memoryFilePath) {
+                    throw new Error('memoryFilePath is required for file provider');
+                }
+                provider = new FileStorageProvider({
+                    filePath: config.options.memoryFilePath,
+                    vectorStoreOptions: config.vectorStoreOptions,
+                });
+                break;
+            }
+            case 'neo4j': {
+                // Configure Neo4j provider
+                const neo4jConfig = {
+                    uri: config.options.neo4jUri,
+                    username: config.options.neo4jUsername,
+                    password: config.options.neo4jPassword,
+                    database: config.options.neo4jDatabase,
+                    vectorIndexName: config.options.neo4jVectorIndexName,
+                    vectorDimensions: config.options.neo4jVectorDimensions,
+                    similarityFunction: config.options.neo4jSimilarityFunction,
+                };
+                provider = new Neo4jStorageProvider({
+                    config: neo4jConfig,
+                    decayConfig: config.options.decayConfig
+                        ? {
+                            enabled: config.options.decayConfig.enabled ?? true,
+                            halfLifeDays: config.options.decayConfig.halfLifeDays,
+                            minConfidence: config.options.decayConfig.minConfidence,
+                        }
+                        : undefined,
+                });
+                break;
+            }
+            default:
+                throw new Error(`Unsupported provider type: ${config.type}`);
+        }
+        // Track the provider as connected
+        this.connectedProviders.add(provider);
+        return provider;
+    }
+    /**
+     * Get a default storage provider (Neo4j-based)
+     * @returns A default Neo4jStorageProvider instance
+     */
+    getDefaultProvider() {
+        // Create a Neo4j provider with default settings
+        const provider = new Neo4jStorageProvider();
+        this.connectedProviders.add(provider);
+        return provider;
+    }
+    /**
+     * Check if a provider is connected
+     * @param provider The provider to check
+     * @returns True if the provider is connected, false otherwise
+     */
+    isProviderConnected(provider) {
+        return this.connectedProviders.has(provider);
+    }
+    /**
+     * Disconnect a provider
+     * @param provider The provider to disconnect
+     */
+    disconnectProvider(provider) {
+        this.connectedProviders.delete(provider);
+    }
+    /**
+     * Cleanup provider resources and disconnect
+     * @param provider The provider to cleanup
+     */
+    async cleanupProvider(provider) {
+        if (this.isProviderConnected(provider)) {
+            if (provider.cleanup) {
+                await provider.cleanup();
+            }
+            this.disconnectProvider(provider);
+        }
+    }
+    /**
+     * Cleanup all connected providers
+     */
+    async cleanupAllProviders() {
+        const providers = Array.from(this.connectedProviders);
+        await Promise.all(providers.map((provider) => this.cleanupProvider(provider)));
+    }
+}
+//# sourceMappingURL=StorageProviderFactory.js.map

package/dist/storage/StorageProviderFactory.js.map

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