@danielsimonjr/memory-mcp 12.2.3 → 12.5.2

package/dist/search/EmbeddingService.js

@@ -1,358 +0,0 @@
-/**
- * Embedding Service
- *
- * Phase 4 Sprint 10: Provides embedding abstractions for semantic search.
- * Supports multiple providers: OpenAI (cloud) and local (transformers.js).
- *
- * @module search/EmbeddingService
- */
-import { EMBEDDING_DEFAULTS, OPENAI_API_CONFIG, getEmbeddingConfig, } from '../utils/constants.js';
-/**
- * OpenAI Embedding Service
- *
- * Uses OpenAI's text-embedding-3-small model for generating embeddings.
- * Supports single and batch embedding with rate limit handling.
- *
- * @example
- * ```typescript
- * const service = new OpenAIEmbeddingService('sk-...');
- * const embedding = await service.embed("Hello world");
- * console.log(`Generated ${embedding.length} dimensions`);
- * ```
- */
-export class OpenAIEmbeddingService {
-    dimensions;
-    provider = 'openai';
-    model;
-    apiKey;
-    /**
-     * Create an OpenAI embedding service.
-     *
-     * @param apiKey - OpenAI API key
-     * @param model - Optional model override (default: text-embedding-3-small)
-     */
-    constructor(apiKey, model) {
-        if (!apiKey) {
-            throw new Error('OpenAI API key is required');
-        }
-        this.apiKey = apiKey;
-        this.model = model || EMBEDDING_DEFAULTS.OPENAI_MODEL;
-        this.dimensions = EMBEDDING_DEFAULTS.OPENAI_DIMENSIONS;
-    }
-    /**
-     * Check if the service is ready.
-     */
-    async isReady() {
-        return !!this.apiKey;
-    }
-    /**
-     * Generate embedding for a single text.
-     *
-     * @param text - Text to embed
-     * @returns Embedding vector
-     */
-    async embed(text) {
-        const results = await this.embedBatch([text]);
-        return results[0];
-    }
-    /**
-     * Generate embeddings for multiple texts in batch.
-     *
-     * @param texts - Array of texts to embed
-     * @returns Array of embedding vectors
-     */
-    async embedBatch(texts) {
-        if (texts.length === 0) {
-            return [];
-        }
-        // Split into batches if needed
-        const maxBatchSize = EMBEDDING_DEFAULTS.OPENAI_MAX_BATCH_SIZE;
-        const results = [];
-        for (let i = 0; i < texts.length; i += maxBatchSize) {
-            const batch = texts.slice(i, i + maxBatchSize);
-            const batchResults = await this.embedBatchInternal(batch);
-            results.push(...batchResults);
-        }
-        return results;
-    }
-    /**
-     * Internal batch embedding with retry logic.
-     */
-    async embedBatchInternal(texts) {
-        let lastError = null;
-        let backoff = OPENAI_API_CONFIG.INITIAL_BACKOFF_MS;
-        for (let attempt = 0; attempt <= OPENAI_API_CONFIG.MAX_RETRIES; attempt++) {
-            try {
-                const response = await fetch(`${OPENAI_API_CONFIG.BASE_URL}${OPENAI_API_CONFIG.EMBEDDINGS_ENDPOINT}`, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'Authorization': `Bearer ${this.apiKey}`,
-                    },
-                    body: JSON.stringify({
-                        model: this.model,
-                        input: texts,
-                    }),
-                });
-                if (!response.ok) {
-                    const errorBody = await response.text();
-                    // Handle rate limiting
-                    if (response.status === 429) {
-                        if (attempt < OPENAI_API_CONFIG.MAX_RETRIES) {
-                            await this.sleep(backoff);
-                            backoff = Math.min(backoff * 2, OPENAI_API_CONFIG.MAX_BACKOFF_MS);
-                            continue;
-                        }
-                    }
-                    throw new Error(`OpenAI API error: ${response.status} - ${errorBody}`);
-                }
-                const data = await response.json();
-                // Sort by index to ensure correct order
-                const sortedData = [...data.data].sort((a, b) => a.index - b.index);
-                return sortedData.map(item => item.embedding);
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                // Retry on network errors
-                if (attempt < OPENAI_API_CONFIG.MAX_RETRIES && this.isRetryableError(error)) {
-                    await this.sleep(backoff);
-                    backoff = Math.min(backoff * 2, OPENAI_API_CONFIG.MAX_BACKOFF_MS);
-                    continue;
-                }
-                throw lastError;
-            }
-        }
-        throw lastError || new Error('Failed to generate embeddings after retries');
-    }
-    /**
-     * Check if an error is retryable.
-     */
-    isRetryableError(error) {
-        if (error instanceof Error) {
-            // Network errors and rate limits are retryable
-            return error.message.includes('fetch') ||
-                error.message.includes('network') ||
-                error.message.includes('429');
-        }
-        return false;
-    }
-    /**
-     * Sleep for a given duration.
-     */
-    sleep(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
-    }
-}
-/**
- * Local Embedding Service
- *
- * Uses @xenova/transformers for local embedding generation.
- * No API calls needed - runs entirely offline after initial model download.
- *
- * Note: Requires @xenova/transformers to be installed as an optional dependency.
- * If not available, initialization will fail gracefully.
- *
- * @example
- * ```typescript
- * const service = new LocalEmbeddingService();
- * await service.initialize();
- * const embedding = await service.embed("Hello world");
- * ```
- */
-export class LocalEmbeddingService {
-    dimensions = EMBEDDING_DEFAULTS.LOCAL_DIMENSIONS;
-    provider = 'local';
-    model;
-    pipeline = null;
-    initialized = false;
-    initPromise = null;
-    /**
-     * Create a local embedding service.
-     *
-     * @param model - Optional model override (default: Xenova/all-MiniLM-L6-v2)
-     */
-    constructor(model) {
-        this.model = model || EMBEDDING_DEFAULTS.LOCAL_MODEL;
-    }
-    /**
-     * Initialize the model pipeline.
-     * Must be called before using embed/embedBatch.
-     */
-    async initialize() {
-        if (this.initialized)
-            return;
-        if (this.initPromise) {
-            return this.initPromise;
-        }
-        this.initPromise = this.initializeInternal();
-        return this.initPromise;
-    }
-    /**
-     * Internal initialization.
-     */
-    async initializeInternal() {
-        try {
-            // Dynamic import to allow optional dependency
-            // @ts-expect-error - @xenova/transformers is an optional peer dependency
-            const transformers = await import('@xenova/transformers');
-            const { pipeline } = transformers;
-            this.pipeline = await pipeline('feature-extraction', this.model);
-            this.initialized = true;
-        }
-        catch (error) {
-            this.initPromise = null;
-            throw new Error(`Failed to initialize local embedding service: ${error instanceof Error ? error.message : String(error)}. ` +
-                'Make sure @xenova/transformers is installed.');
-        }
-    }
-    /**
-     * Check if the service is ready.
-     */
-    async isReady() {
-        if (!this.initialized && !this.initPromise) {
-            try {
-                await this.initialize();
-            }
-            catch {
-                return false;
-            }
-        }
-        return this.initialized;
-    }
-    /**
-     * Generate embedding for a single text.
-     *
-     * @param text - Text to embed
-     * @returns Embedding vector
-     */
-    async embed(text) {
-        await this.ensureInitialized();
-        const pipelineFn = this.pipeline;
-        const output = await pipelineFn(text, { pooling: 'mean', normalize: true });
-        return Array.from(output.data);
-    }
-    /**
-     * Generate embeddings for multiple texts in batch.
-     * Note: Local processing is done sequentially to avoid memory issues.
-     *
-     * @param texts - Array of texts to embed
-     * @returns Array of embedding vectors
-     */
-    async embedBatch(texts) {
-        await this.ensureInitialized();
-        const results = [];
-        for (const text of texts) {
-            const embedding = await this.embed(text);
-            results.push(embedding);
-        }
-        return results;
-    }
-    /**
-     * Ensure the service is initialized.
-     */
-    async ensureInitialized() {
-        if (!this.initialized) {
-            await this.initialize();
-        }
-    }
-}
-/**
- * Mock Embedding Service for testing
- *
- * Generates deterministic mock embeddings for testing purposes.
- * Useful for unit tests that don't need real embeddings.
- */
-export class MockEmbeddingService {
-    dimensions;
-    provider = 'mock';
-    model = 'mock-model';
-    /**
-     * Create a mock embedding service.
-     *
-     * @param dimensions - Number of dimensions for mock embeddings
-     */
-    constructor(dimensions = 384) {
-        this.dimensions = dimensions;
-    }
-    /**
-     * Check if the service is ready.
-     */
-    async isReady() {
-        return true;
-    }
-    /**
-     * Generate a deterministic mock embedding for a text.
-     *
-     * @param text - Text to embed
-     * @returns Mock embedding vector
-     */
-    async embed(text) {
-        // Generate deterministic embedding based on text hash
-        const hash = this.hashString(text);
-        const embedding = [];
-        for (let i = 0; i < this.dimensions; i++) {
-            // Use hash and index to generate deterministic values
-            const value = Math.sin(hash + i * 0.1) * 0.5;
-            embedding.push(value);
-        }
-        // Normalize the vector
-        return this.normalize(embedding);
-    }
-    /**
-     * Generate mock embeddings for multiple texts.
-     *
-     * @param texts - Array of texts to embed
-     * @returns Array of mock embedding vectors
-     */
-    async embedBatch(texts) {
-        return Promise.all(texts.map(text => this.embed(text)));
-    }
-    /**
-     * Simple string hash function.
-     */
-    hashString(str) {
-        let hash = 0;
-        for (let i = 0; i < str.length; i++) {
-            const char = str.charCodeAt(i);
-            hash = ((hash << 5) - hash) + char;
-            hash = hash & hash; // Convert to 32bit integer
-        }
-        return hash;
-    }
-    /**
-     * Normalize a vector to unit length.
-     */
-    normalize(vector) {
-        let magnitude = 0;
-        for (const v of vector) {
-            magnitude += v * v;
-        }
-        magnitude = Math.sqrt(magnitude);
-        if (magnitude === 0) {
-            return vector;
-        }
-        return vector.map(v => v / magnitude);
-    }
-}
-/**
- * Create an embedding service based on configuration.
- *
- * @param config - Optional configuration override
- * @returns Embedding service instance, or null if provider is 'none'
- */
-export function createEmbeddingService(config) {
-    const envConfig = getEmbeddingConfig();
-    const mergedConfig = { ...envConfig, ...config };
-    switch (mergedConfig.provider) {
-        case 'openai':
-            if (!mergedConfig.apiKey) {
-                throw new Error('OpenAI API key is required. Set MEMORY_OPENAI_API_KEY environment variable or provide apiKey in config.');
-            }
-            return new OpenAIEmbeddingService(mergedConfig.apiKey, mergedConfig.model);
-        case 'local':
-            return new LocalEmbeddingService(mergedConfig.model);
-        case 'none':
-        default:
-            return null;
-    }
-}

package/dist/search/FuzzySearch.d.ts

@@ -1,118 +0,0 @@
-/**
- * Fuzzy Search
- *
- * Search with typo tolerance using Levenshtein distance similarity.
- * Uses workerpool for parallel processing on large datasets.
- *
- * @module search/FuzzySearch
- */
-import type { KnowledgeGraph } from '../types/index.js';
-import type { GraphStorage } from '../core/GraphStorage.js';
-/**
- * Default fuzzy search similarity threshold (70% match required).
- * Lower values are more permissive (more typos tolerated).
- * Higher values are stricter (fewer typos tolerated).
- */
-export declare const DEFAULT_FUZZY_THRESHOLD = 0.7;
-/**
- * Options for FuzzySearch constructor.
- */
-export interface FuzzySearchOptions {
-    /**
-     * Whether to use worker pool for parallel processing.
-     * Set to false for testing or when workers are not available.
-     * Default: true
-     */
-    useWorkerPool?: boolean;
-}
-/**
- * Performs fuzzy search with configurable similarity threshold.
- */
-export declare class FuzzySearch {
-    private storage;
-    /**
-     * Phase 4 Sprint 3: Result cache for fuzzy search.
-     * Maps cache key -> cached entity names.
-     */
-    private fuzzyResultCache;
-    /**
-     * Phase 8: Worker pool using workerpool library.
-     * Initialized lazily when needed.
-     */
-    private workerPool;
-    /**
-     * Phase 7 Sprint 3: Path to the worker script.
-     */
-    private workerPath;
-    /**
-     * Phase 8: Whether to use worker pool for parallel processing.
-     * Can be disabled for testing or when workers are not available.
-     */
-    private useWorkerPool;
-    constructor(storage: GraphStorage, options?: FuzzySearchOptions);
-    /**
-     * Phase 4 Sprint 3: Generate cache key for fuzzy search parameters.
-     */
-    private generateCacheKey;
-    /**
-     * Phase 4 Sprint 3: Clear the fuzzy search cache.
-     */
-    clearCache(): void;
-    /**
-     * Phase 4 Sprint 3: Invalidate stale cache entries.
-     */
-    private cleanupCache;
-    /**
-     * Fuzzy search for entities with typo tolerance and pagination.
-     *
-     * Uses Levenshtein distance to calculate similarity between strings.
-     * Matches if similarity >= threshold (0.0 to 1.0).
-     *
-     * Phase 4 Sprint 3: Implements result caching for repeated queries.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold (0.0 to 1.0), default DEFAULT_FUZZY_THRESHOLD
-     * @param tags - Optional tags filter
-     * @param minImportance - Optional minimum importance
-     * @param maxImportance - Optional maximum importance
-     * @param offset - Number of results to skip (default: 0)
-     * @param limit - Maximum number of results (default: 50, max: 200)
-     * @returns Filtered knowledge graph with fuzzy matches and pagination applied
-     */
-    fuzzySearch(query: string, threshold?: number, tags?: string[], minImportance?: number, maxImportance?: number, offset?: number, limit?: number): Promise<KnowledgeGraph>;
-    /**
-     * Phase 4 Sprint 3: Perform the actual fuzzy matching logic.
-     * Extracted from fuzzySearch for cleaner code structure.
-     */
-    private performFuzzyMatch;
-    /**
-     * Check if two already-lowercase strings match with fuzzy logic.
-     *
-     * OPTIMIZED: Skips toLowerCase() calls when strings are already lowercase.
-     *
-     * @param s1 - First string (already lowercase)
-     * @param s2 - Second string (already lowercase)
-     * @param threshold - Similarity threshold (0.0 to 1.0)
-     * @returns True if strings match fuzzily
-     */
-    private isFuzzyMatchLower;
-    /**
-     * Phase 8: Perform fuzzy search using workerpool for parallel processing.
-     *
-     * Splits entities into chunks and processes them in parallel using worker threads.
-     * Falls back to single-threaded search if worker execution fails.
-     *
-     * @param query - Search query
-     * @param threshold - Similarity threshold
-     * @param entities - Entities to search
-     * @returns Array of matched entities
-     */
-    private searchWithWorkers;
-    /**
-     * Phase 8: Shutdown the worker pool and clean up resources.
-     *
-     * Should be called when FuzzySearch is no longer needed.
-     */
-    shutdown(): Promise<void>;
-}
-//# sourceMappingURL=FuzzySearch.d.ts.map

package/dist/search/FuzzySearch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"FuzzySearch.d.ts","sourceRoot":"","sources":["../../src/search/FuzzySearch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAU,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAQ5D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AA4C3C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,WAAW;IAwBV,OAAO,CAAC,OAAO;IAvB3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAA2C;IAEnE;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAqB;IAEvC;;OAEG;IACH,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAU;gBAEX,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB;IAmB3E;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;;;;;;;;;;;;OAgBG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAgC,EAC3C,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,cAAc,CAAC;IAsE1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAezB;;;;;;;;;;OAUG;YACW,iBAAiB;IAiE/B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAMhC"}