@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/search/RankedSearch.js

@@ -0,0 +1,206 @@
+/**
+ * Ranked Search
+ *
+ * TF-IDF relevance-based search with scoring and pre-calculated indexes.
+ *
+ * @module search/RankedSearch
+ */
+import { calculateTFIDF, tokenize } from '../utils/tfidf.js';
+import { SEARCH_LIMITS } from '../utils/constants.js';
+import { TFIDFIndexManager } from './TFIDFIndexManager.js';
+/**
+ * Performs TF-IDF ranked search with optional pre-calculated indexes.
+ */
+export class RankedSearch {
+    storage;
+    indexManager = null;
+    constructor(storage, storageDir) {
+        this.storage = storage;
+        // Initialize index manager if storage directory is provided
+        if (storageDir) {
+            this.indexManager = new TFIDFIndexManager(storageDir);
+        }
+    }
+    /**
+     * Initialize and build the TF-IDF index for fast searches.
+     *
+     * Should be called after graph changes to keep index up-to-date.
+     */
+    async buildIndex() {
+        if (!this.indexManager) {
+            throw new Error('Index manager not initialized. Provide storageDir to constructor.');
+        }
+        const graph = await this.storage.loadGraph();
+        await this.indexManager.buildIndex(graph);
+        await this.indexManager.saveIndex();
+    }
+    /**
+     * Update the index incrementally after entity changes.
+     *
+     * @param changedEntityNames - Names of entities that were created, updated, or deleted
+     */
+    async updateIndex(changedEntityNames) {
+        if (!this.indexManager) {
+            return; // No index manager, skip
+        }
+        const graph = await this.storage.loadGraph();
+        await this.indexManager.updateIndex(graph, changedEntityNames);
+        await this.indexManager.saveIndex();
+    }
+    /**
+     * Load the TF-IDF index from disk if available.
+     */
+    async ensureIndexLoaded() {
+        if (!this.indexManager) {
+            return null;
+        }
+        // Return cached index if already loaded
+        const cached = this.indexManager.getIndex();
+        if (cached) {
+            return cached;
+        }
+        // Try to load from disk
+        return await this.indexManager.loadIndex();
+    }
+    /**
+     * Search with TF-IDF relevance ranking.
+     *
+     * Uses pre-calculated index if available, falls back to on-the-fly calculation.
+     *
+     * @param query - Search query
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @param limit - Maximum results to return (default 50, max 200)
+     * @returns Array of search results sorted by relevance
+     */
+    async searchNodesRanked(query, tags, minImportance, maxImportance, limit = SEARCH_LIMITS.DEFAULT) {
+        // Enforce maximum search limit
+        const effectiveLimit = Math.min(limit, SEARCH_LIMITS.MAX);
+        const graph = await this.storage.loadGraph();
+        const normalizedTags = tags?.map(tag => tag.toLowerCase());
+        // Filter entities by tags and importance
+        const filteredEntities = graph.entities.filter(e => {
+            // Tag filter
+            if (normalizedTags && normalizedTags.length > 0) {
+                if (!e.tags || e.tags.length === 0)
+                    return false;
+                const entityTags = e.tags.map(tag => tag.toLowerCase());
+                if (!normalizedTags.some(tag => entityTags.includes(tag)))
+                    return false;
+            }
+            // Importance filter
+            if (minImportance !== undefined && (e.importance === undefined || e.importance < minImportance)) {
+                return false;
+            }
+            if (maxImportance !== undefined && (e.importance === undefined || e.importance > maxImportance)) {
+                return false;
+            }
+            return true;
+        });
+        // Try to use pre-calculated index
+        const index = await this.ensureIndexLoaded();
+        const queryTerms = tokenize(query);
+        if (index) {
+            // Use pre-calculated index for fast search
+            return this.searchWithIndex(filteredEntities, queryTerms, index, effectiveLimit);
+        }
+        else {
+            // Fall back to on-the-fly calculation
+            return this.searchWithoutIndex(filteredEntities, queryTerms, effectiveLimit);
+        }
+    }
+    /**
+     * Search using pre-calculated TF-IDF index (fast path).
+     */
+    searchWithIndex(entities, queryTerms, index, limit) {
+        const results = [];
+        for (const entity of entities) {
+            const docVector = index.documents.get(entity.name);
+            if (!docVector) {
+                continue; // Entity not in index
+            }
+            // Calculate total terms in document (sum of all term frequencies)
+            const totalTerms = Object.values(docVector.terms).reduce((sum, count) => sum + count, 0);
+            if (totalTerms === 0)
+                continue;
+            // Calculate score using pre-calculated term frequencies and IDF
+            let totalScore = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                const termCount = docVector.terms[term] || 0;
+                const idf = index.idf.get(term) || 0;
+                // Calculate TF-IDF: (termCount / totalTerms) * IDF
+                const tf = termCount / totalTerms;
+                const tfidf = tf * idf;
+                totalScore += tfidf;
+                // Track which fields matched
+                if (termCount > 0) {
+                    if (entity.name.toLowerCase().includes(term)) {
+                        matchedFields.name = true;
+                    }
+                    if (entity.entityType.toLowerCase().includes(term)) {
+                        matchedFields.entityType = true;
+                    }
+                    const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
+                    if (matchedObs.length > 0) {
+                        matchedFields.observations = matchedObs;
+                    }
+                }
+            }
+            // Only include entities with non-zero scores
+            if (totalScore > 0) {
+                results.push({
+                    entity,
+                    score: totalScore,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and apply limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /**
+     * Search without index (on-the-fly calculation, slow path).
+     */
+    searchWithoutIndex(entities, queryTerms, limit) {
+        const results = [];
+        const documents = entities.map(e => [e.name, e.entityType, ...e.observations].join(' '));
+        for (let i = 0; i < entities.length; i++) {
+            const entity = entities[i];
+            const document = documents[i];
+            // Calculate score for each query term
+            let totalScore = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                const score = calculateTFIDF(term, document, documents);
+                totalScore += score;
+                // Track which fields matched
+                if (entity.name.toLowerCase().includes(term)) {
+                    matchedFields.name = true;
+                }
+                if (entity.entityType.toLowerCase().includes(term)) {
+                    matchedFields.entityType = true;
+                }
+                const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
+                if (matchedObs.length > 0) {
+                    matchedFields.observations = matchedObs;
+                }
+            }
+            // Only include entities with non-zero scores
+            if (totalScore > 0) {
+                results.push({
+                    entity,
+                    score: totalScore,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and apply limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+}

package/dist/search/SavedSearchManager.js

@@ -0,0 +1,145 @@
+/**
+ * Saved Search Manager
+ *
+ * Manages persistent saved searches with JSONL storage.
+ *
+ * @module search/SavedSearchManager
+ */
+import * as fs from 'fs/promises';
+/**
+ * Manages saved search queries with usage tracking.
+ */
+export class SavedSearchManager {
+    savedSearchesFilePath;
+    basicSearch;
+    constructor(savedSearchesFilePath, basicSearch) {
+        this.savedSearchesFilePath = savedSearchesFilePath;
+        this.basicSearch = basicSearch;
+    }
+    /**
+     * Load all saved searches from JSONL file.
+     *
+     * @returns Array of saved searches
+     */
+    async loadSavedSearches() {
+        try {
+            const data = await fs.readFile(this.savedSearchesFilePath, 'utf-8');
+            const lines = data.split('\n').filter((line) => line.trim() !== '');
+            return lines.map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Save searches to JSONL file.
+     *
+     * @param searches - Array of saved searches
+     */
+    async saveSavedSearches(searches) {
+        const lines = searches.map(s => JSON.stringify(s));
+        await fs.writeFile(this.savedSearchesFilePath, lines.join('\n'));
+    }
+    /**
+     * Save a search query for later reuse.
+     *
+     * @param search - Search parameters (without createdAt, useCount, lastUsed)
+     * @returns The newly created saved search
+     * @throws Error if search name already exists
+     */
+    async saveSearch(search) {
+        const searches = await this.loadSavedSearches();
+        // Check if name already exists
+        if (searches.some(s => s.name === search.name)) {
+            throw new Error(`Saved search with name "${search.name}" already exists`);
+        }
+        const newSearch = {
+            ...search,
+            createdAt: new Date().toISOString(),
+            useCount: 0,
+        };
+        searches.push(newSearch);
+        await this.saveSavedSearches(searches);
+        return newSearch;
+    }
+    /**
+     * List all saved searches.
+     *
+     * @returns Array of all saved searches
+     */
+    async listSavedSearches() {
+        return await this.loadSavedSearches();
+    }
+    /**
+     * Get a specific saved search by name.
+     *
+     * @param name - Search name
+     * @returns Saved search or null if not found
+     */
+    async getSavedSearch(name) {
+        const searches = await this.loadSavedSearches();
+        return searches.find(s => s.name === name) || null;
+    }
+    /**
+     * Execute a saved search by name.
+     *
+     * Updates usage statistics (lastUsed, useCount) before executing.
+     *
+     * @param name - Search name
+     * @returns Search results as knowledge graph
+     * @throws Error if search not found
+     */
+    async executeSavedSearch(name) {
+        const searches = await this.loadSavedSearches();
+        const search = searches.find(s => s.name === name);
+        if (!search) {
+            throw new Error(`Saved search "${name}" not found`);
+        }
+        // Update usage statistics
+        search.lastUsed = new Date().toISOString();
+        search.useCount++;
+        await this.saveSavedSearches(searches);
+        // Execute the search using BasicSearch
+        return await this.basicSearch.searchNodes(search.query, search.tags, search.minImportance, search.maxImportance);
+    }
+    /**
+     * Delete a saved search.
+     *
+     * @param name - Search name
+     * @returns True if deleted, false if not found
+     */
+    async deleteSavedSearch(name) {
+        const searches = await this.loadSavedSearches();
+        const initialLength = searches.length;
+        const filtered = searches.filter(s => s.name !== name);
+        if (filtered.length === initialLength) {
+            return false; // Search not found
+        }
+        await this.saveSavedSearches(filtered);
+        return true;
+    }
+    /**
+     * Update a saved search.
+     *
+     * Cannot update name, createdAt, useCount, or lastUsed fields.
+     *
+     * @param name - Search name
+     * @param updates - Partial search with fields to update
+     * @returns Updated saved search
+     * @throws Error if search not found
+     */
+    async updateSavedSearch(name, updates) {
+        const searches = await this.loadSavedSearches();
+        const search = searches.find(s => s.name === name);
+        if (!search) {
+            throw new Error(`Saved search "${name}" not found`);
+        }
+        // Apply updates
+        Object.assign(search, updates);
+        await this.saveSavedSearches(searches);
+        return search;
+    }
+}

package/dist/search/SearchManager.js

@@ -0,0 +1,305 @@
+/**
+ * Search Manager
+ *
+ * Orchestrates all search types (basic, ranked, boolean, fuzzy).
+ *
+ * @module search/SearchManager
+ */
+import { BasicSearch } from './BasicSearch.js';
+import { RankedSearch } from './RankedSearch.js';
+import { BooleanSearch } from './BooleanSearch.js';
+import { FuzzySearch } from './FuzzySearch.js';
+import { SearchSuggestions } from './SearchSuggestions.js';
+import { SavedSearchManager } from './SavedSearchManager.js';
+/**
+ * Unified search manager providing access to all search types.
+ */
+export class SearchManager {
+    basicSearch;
+    rankedSearch;
+    booleanSearcher;
+    fuzzySearcher;
+    searchSuggestions;
+    savedSearchManager;
+    constructor(storage, savedSearchesFilePath) {
+        this.basicSearch = new BasicSearch(storage);
+        this.rankedSearch = new RankedSearch(storage);
+        this.booleanSearcher = new BooleanSearch(storage);
+        this.fuzzySearcher = new FuzzySearch(storage);
+        this.searchSuggestions = new SearchSuggestions(storage);
+        this.savedSearchManager = new SavedSearchManager(savedSearchesFilePath, this.basicSearch);
+    }
+    // ==================== Basic Search ====================
+    /**
+     * Perform a simple text-based search across entity names and observations.
+     *
+     * This is the primary search method that searches through entity names,
+     * observations, and types using case-insensitive substring matching.
+     * Optionally filter by tags and importance range.
+     *
+     * @param query - Text to search for (case-insensitive, searches names/observations/types)
+     * @param tags - Optional array of tags to filter results (lowercase)
+     * @param minImportance - Optional minimum importance value (0-10)
+     * @param maxImportance - Optional maximum importance value (0-10)
+     * @returns KnowledgeGraph containing matching entities and their relations
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // Simple text search
+     * const results = await manager.searchNodes('Alice');
+     *
+     * // Search with tag filter
+     * const engineeringResults = await manager.searchNodes('project', ['engineering']);
+     *
+     * // Search with importance range
+     * const importantResults = await manager.searchNodes('critical', undefined, 8, 10);
+     *
+     * // Combined filters
+     * const filtered = await manager.searchNodes('bug', ['backend'], 5, 10);
+     * ```
+     */
+    async searchNodes(query, tags, minImportance, maxImportance) {
+        return this.basicSearch.searchNodes(query, tags, minImportance, maxImportance);
+    }
+    /**
+     * Open specific nodes by name.
+     *
+     * @param names - Array of entity names
+     * @returns Knowledge graph with specified entities
+     */
+    async openNodes(names) {
+        return this.basicSearch.openNodes(names);
+    }
+    /**
+     * Search by date range.
+     *
+     * @param startDate - Optional start date (ISO 8601)
+     * @param endDate - Optional end date (ISO 8601)
+     * @param entityType - Optional entity type filter
+     * @param tags - Optional tags filter
+     * @returns Filtered knowledge graph
+     */
+    async searchByDateRange(startDate, endDate, entityType, tags) {
+        return this.basicSearch.searchByDateRange(startDate, endDate, entityType, tags);
+    }
+    // ==================== Ranked Search ====================
+    /**
+     * Perform TF-IDF ranked search with relevance scoring.
+     *
+     * Uses Term Frequency-Inverse Document Frequency algorithm to rank results
+     * by relevance to the query. Results are sorted by score (highest first).
+     * This is ideal for finding the most relevant entities for a search query.
+     *
+     * @param query - Search query (analyzed for term frequency)
+     * @param tags - Optional array of tags to filter results (lowercase)
+     * @param minImportance - Optional minimum importance value (0-10)
+     * @param maxImportance - Optional maximum importance value (0-10)
+     * @param limit - Maximum number of results to return (default: 50, max: 200)
+     * @returns Array of SearchResult objects sorted by relevance score (descending)
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // Basic ranked search
+     * const results = await manager.searchNodesRanked('machine learning algorithms');
+     * results.forEach(r => {
+     *   console.log(`${r.entity.name} (score: ${r.score})`);
+     * });
+     *
+     * // Limit to top 10 most relevant results
+     * const top10 = await manager.searchNodesRanked('database optimization', undefined, undefined, undefined, 10);
+     *
+     * // Ranked search with filters
+     * const relevantImportant = await manager.searchNodesRanked(
+     *   'security vulnerability',
+     *   ['security', 'critical'],
+     *   8,
+     *   10,
+     *   20
+     * );
+     * ```
+     */
+    async searchNodesRanked(query, tags, minImportance, maxImportance, limit) {
+        return this.rankedSearch.searchNodesRanked(query, tags, minImportance, maxImportance, limit);
+    }
+    // ==================== Boolean Search ====================
+    /**
+     * Perform boolean search with AND, OR, NOT operators.
+     *
+     * Supports complex boolean logic for precise search queries.
+     * Use AND/OR/NOT operators (case-insensitive) to combine search terms.
+     * Parentheses are supported for grouping.
+     *
+     * @param query - Boolean query string (e.g., "alice AND bob", "frontend OR backend NOT legacy")
+     * @param tags - Optional array of tags to filter results (lowercase)
+     * @param minImportance - Optional minimum importance value (0-10)
+     * @param maxImportance - Optional maximum importance value (0-10)
+     * @returns KnowledgeGraph containing entities matching the boolean expression
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // AND operator - entities matching all terms
+     * const both = await manager.booleanSearch('database AND performance');
+     *
+     * // OR operator - entities matching any term
+     * const either = await manager.booleanSearch('frontend OR backend');
+     *
+     * // NOT operator - exclude terms
+     * const excluding = await manager.booleanSearch('API NOT deprecated');
+     *
+     * // Complex queries with grouping
+     * const complex = await manager.booleanSearch('(react OR vue) AND (component OR hook) NOT legacy');
+     * ```
+     */
+    async booleanSearch(query, tags, minImportance, maxImportance) {
+        return this.booleanSearcher.booleanSearch(query, tags, minImportance, maxImportance);
+    }
+    // ==================== Fuzzy Search ====================
+    /**
+     * Perform fuzzy search with typo tolerance.
+     *
+     * Uses Levenshtein distance to find entities that approximately match the query,
+     * making it ideal for handling typos and variations in spelling.
+     * Higher threshold values require closer matches.
+     *
+     * @param query - Search query (will match approximate spellings)
+     * @param threshold - Similarity threshold from 0.0 (very lenient) to 1.0 (exact match). Default: 0.7
+     * @param tags - Optional array of tags to filter results (lowercase)
+     * @param minImportance - Optional minimum importance value (0-10)
+     * @param maxImportance - Optional maximum importance value (0-10)
+     * @returns KnowledgeGraph containing entities with similar names/observations
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // Find entities even with typos
+     * const results = await manager.fuzzySearch('databse'); // Will match "database"
+     *
+     * // Adjust threshold for strictness
+     * const strict = await manager.fuzzySearch('optmization', 0.9); // Requires very close match
+     * const lenient = await manager.fuzzySearch('optmization', 0.6); // More tolerant of differences
+     *
+     * // Fuzzy search with filters
+     * const filtered = await manager.fuzzySearch('secrity', 0.7, ['important'], 7, 10);
+     * ```
+     */
+    async fuzzySearch(query, threshold, tags, minImportance, maxImportance) {
+        return this.fuzzySearcher.fuzzySearch(query, threshold, tags, minImportance, maxImportance);
+    }
+    // ==================== Search Suggestions ====================
+    /**
+     * Get search suggestions for a query.
+     *
+     * @param query - Search query
+     * @param maxSuggestions - Maximum suggestions to return
+     * @returns Array of suggested terms
+     */
+    async getSearchSuggestions(query, maxSuggestions) {
+        return this.searchSuggestions.getSearchSuggestions(query, maxSuggestions);
+    }
+    // ==================== Saved Searches ====================
+    /**
+     * Save a search query for later reuse.
+     *
+     * Saved searches store query parameters and can be re-executed later.
+     * The system tracks usage count and last used timestamp automatically.
+     *
+     * @param search - Search parameters (name, query, and optional filters)
+     * @returns Newly created SavedSearch object with metadata
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // Save a simple search
+     * const saved = await manager.saveSearch({
+     *   name: 'High Priority Bugs',
+     *   query: 'bug',
+     *   tags: ['critical'],
+     *   minImportance: 8
+     * });
+     *
+     * // Save a complex search
+     * await manager.saveSearch({
+     *   name: 'Recent Frontend Work',
+     *   query: 'component OR hook',
+     *   tags: ['frontend', 'react'],
+     *   searchType: 'boolean'
+     * });
+     * ```
+     */
+    async saveSearch(search) {
+        return this.savedSearchManager.saveSearch(search);
+    }
+    /**
+     * List all saved searches.
+     *
+     * @returns Array of saved searches
+     */
+    async listSavedSearches() {
+        return this.savedSearchManager.listSavedSearches();
+    }
+    /**
+     * Get a saved search by name.
+     *
+     * @param name - Search name
+     * @returns Saved search or null
+     */
+    async getSavedSearch(name) {
+        return this.savedSearchManager.getSavedSearch(name);
+    }
+    /**
+     * Execute a saved search by name.
+     *
+     * Runs a previously saved search with its stored parameters.
+     * Automatically updates the search's useCount and lastUsed timestamp.
+     *
+     * @param name - The unique name of the saved search to execute
+     * @returns KnowledgeGraph containing the search results
+     * @throws Error if saved search not found
+     *
+     * @example
+     * ```typescript
+     * const manager = new SearchManager(storage, savedSearchesPath);
+     *
+     * // Execute a saved search
+     * const results = await manager.executeSavedSearch('High Priority Bugs');
+     * console.log(`Found ${results.entities.length} high priority bugs`);
+     *
+     * // Handle missing saved search
+     * try {
+     *   await manager.executeSavedSearch('NonExistent');
+     * } catch (error) {
+     *   console.error('Search not found');
+     * }
+     * ```
+     */
+    async executeSavedSearch(name) {
+        return this.savedSearchManager.executeSavedSearch(name);
+    }
+    /**
+     * Delete a saved search.
+     *
+     * @param name - Search name
+     * @returns True if deleted
+     */
+    async deleteSavedSearch(name) {
+        return this.savedSearchManager.deleteSavedSearch(name);
+    }
+    /**
+     * Update a saved search.
+     *
+     * @param name - Search name
+     * @param updates - Fields to update
+     * @returns Updated saved search
+     */
+    async updateSavedSearch(name, updates) {
+        return this.savedSearchManager.updateSavedSearch(name, updates);
+    }
+}