@danielsimonjr/memory-mcp 0.7.2 → 0.47.1

package/dist/search/RankedSearch.js

@@ -0,0 +1,190 @@
+/**
+ * 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';
+import { SearchFilterChain } from './SearchFilterChain.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();
+        // Apply tag and importance filters using SearchFilterChain
+        const filters = { tags, minImportance, maxImportance };
+        const filteredEntities = SearchFilterChain.applyFilters(graph.entities, filters);
+        // 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/SearchFilterChain.js

@@ -0,0 +1,187 @@
+/**
+ * Search Filter Chain
+ *
+ * Centralizes filter logic for all search implementations to eliminate
+ * duplicate filtering code across BasicSearch, BooleanSearch, FuzzySearch,
+ * and RankedSearch.
+ *
+ * @module search/SearchFilterChain
+ */
+import { normalizeTags, hasMatchingTag } from '../utils/tagUtils.js';
+import { isWithinImportanceRange } from '../utils/filterUtils.js';
+import { validatePagination, applyPagination } from '../utils/paginationUtils.js';
+/**
+ * Centralized filter chain for all search implementations.
+ * Ensures consistent filtering behavior across search types.
+ *
+ * @example
+ * ```typescript
+ * const filters: SearchFilters = { tags: ['important'], minImportance: 5 };
+ * const filtered = SearchFilterChain.applyFilters(entities, filters);
+ * const pagination = SearchFilterChain.validatePagination(0, 50);
+ * const result = SearchFilterChain.paginate(filtered, pagination);
+ * ```
+ */
+export class SearchFilterChain {
+    /**
+     * Applies all filters to an array of entities.
+     * Entities must pass ALL specified filters to be included.
+     *
+     * @param entities - Entities to filter
+     * @param filters - Filter criteria to apply
+     * @returns Filtered entities array
+     */
+    static applyFilters(entities, filters) {
+        // Early return if no filters are active
+        if (!this.hasActiveFilters(filters)) {
+            return entities;
+        }
+        // Pre-normalize tags once for efficiency
+        const normalizedSearchTags = filters.tags?.length
+            ? normalizeTags(filters.tags)
+            : undefined;
+        return entities.filter(entity => this.entityPassesFilters(entity, filters, normalizedSearchTags));
+    }
+    /**
+     * Checks if an entity passes all active filters.
+     * Short-circuits on first failing filter for performance.
+     *
+     * @param entity - Entity to check
+     * @param filters - Filter criteria
+     * @param normalizedSearchTags - Pre-normalized search tags (for efficiency)
+     * @returns true if entity passes all filters
+     */
+    static entityPassesFilters(entity, filters, normalizedSearchTags) {
+        // Tag filter - check if entity has any matching tag
+        if (normalizedSearchTags && normalizedSearchTags.length > 0) {
+            if (!entity.tags || entity.tags.length === 0) {
+                return false;
+            }
+            const entityTags = normalizeTags(entity.tags);
+            const hasMatch = normalizedSearchTags.some(tag => entityTags.includes(tag));
+            if (!hasMatch) {
+                return false;
+            }
+        }
+        // Importance filter
+        if (!isWithinImportanceRange(entity.importance, filters.minImportance, filters.maxImportance)) {
+            return false;
+        }
+        // Entity type filter
+        if (filters.entityType && entity.entityType !== filters.entityType) {
+            return false;
+        }
+        // Created date filter
+        if (filters.createdAfter || filters.createdBefore) {
+            if (!entity.createdAt) {
+                return false;
+            }
+            const createdAt = new Date(entity.createdAt);
+            if (filters.createdAfter && createdAt < new Date(filters.createdAfter)) {
+                return false;
+            }
+            if (filters.createdBefore && createdAt > new Date(filters.createdBefore)) {
+                return false;
+            }
+        }
+        // Modified date filter
+        if (filters.modifiedAfter || filters.modifiedBefore) {
+            if (!entity.lastModified) {
+                return false;
+            }
+            const modifiedAt = new Date(entity.lastModified);
+            if (filters.modifiedAfter && modifiedAt < new Date(filters.modifiedAfter)) {
+                return false;
+            }
+            if (filters.modifiedBefore && modifiedAt > new Date(filters.modifiedBefore)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks if any filters are actually specified.
+     * Used for early return optimization.
+     *
+     * @param filters - Filter criteria to check
+     * @returns true if at least one filter is active
+     */
+    static hasActiveFilters(filters) {
+        return !!((filters.tags && filters.tags.length > 0) ||
+            filters.minImportance !== undefined ||
+            filters.maxImportance !== undefined ||
+            filters.entityType ||
+            filters.createdAfter ||
+            filters.createdBefore ||
+            filters.modifiedAfter ||
+            filters.modifiedBefore);
+    }
+    /**
+     * Validates and returns pagination parameters.
+     * Delegates to paginationUtils.validatePagination.
+     *
+     * @param offset - Starting position
+     * @param limit - Maximum results
+     * @returns Validated pagination object
+     */
+    static validatePagination(offset = 0, limit) {
+        return validatePagination(offset, limit);
+    }
+    /**
+     * Applies pagination to a filtered result set.
+     *
+     * @param entities - Entities to paginate
+     * @param pagination - Validated pagination parameters
+     * @returns Paginated slice of entities
+     */
+    static paginate(entities, pagination) {
+        return applyPagination(entities, pagination);
+    }
+    /**
+     * Convenience method to apply both filters and pagination in one call.
+     *
+     * @param entities - Entities to process
+     * @param filters - Filter criteria
+     * @param offset - Pagination offset
+     * @param limit - Pagination limit
+     * @returns Filtered and paginated entities
+     */
+    static filterAndPaginate(entities, filters, offset = 0, limit) {
+        const filtered = this.applyFilters(entities, filters);
+        const pagination = this.validatePagination(offset, limit);
+        return this.paginate(filtered, pagination);
+    }
+    /**
+     * Applies tag filter only. Useful when other filters are handled separately.
+     *
+     * @param entities - Entities to filter
+     * @param tags - Tags to filter by
+     * @returns Filtered entities
+     */
+    static filterByTags(entities, tags) {
+        if (!tags || tags.length === 0) {
+            return entities;
+        }
+        const normalizedTags = normalizeTags(tags);
+        return entities.filter(entity => {
+            if (!entity.tags || entity.tags.length === 0) {
+                return false;
+            }
+            return hasMatchingTag(entity.tags, normalizedTags);
+        });
+    }
+    /**
+     * Applies importance filter only. Useful when other filters are handled separately.
+     *
+     * @param entities - Entities to filter
+     * @param minImportance - Minimum importance
+     * @param maxImportance - Maximum importance
+     * @returns Filtered entities
+     */
+    static filterByImportance(entities, minImportance, maxImportance) {
+        if (minImportance === undefined && maxImportance === undefined) {
+            return entities;
+        }
+        return entities.filter(entity => isWithinImportanceRange(entity.importance, minImportance, maxImportance));
+    }
+}