@danielsimonjr/memory-mcp 0.7.2 → 0.47.1

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);
+    }
+}

package/dist/search/SearchSuggestions.js

@@ -0,0 +1,57 @@
+/**
+ * Search Suggestions
+ *
+ * Provides "did you mean?" suggestions using Levenshtein distance.
+ *
+ * @module search/SearchSuggestions
+ */
+import { levenshteinDistance } from '../utils/levenshtein.js';
+/**
+ * Generates search suggestions based on entity names and types.
+ */
+export class SearchSuggestions {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Get "did you mean?" suggestions for a query.
+     *
+     * Returns similar entity names and types that might be what the user intended.
+     * Excludes exact matches (similarity < 1.0) and very dissimilar strings (similarity > 0.5).
+     *
+     * @param query - The search query
+     * @param maxSuggestions - Maximum number of suggestions to return (default 5)
+     * @returns Array of suggested entity/type names sorted by similarity
+     */
+    async getSearchSuggestions(query, maxSuggestions = 5) {
+        const graph = await this.storage.loadGraph();
+        const queryLower = query.toLowerCase();
+        const suggestions = [];
+        // Check entity names
+        for (const entity of graph.entities) {
+            const distance = levenshteinDistance(queryLower, entity.name.toLowerCase());
+            const maxLength = Math.max(queryLower.length, entity.name.length);
+            const similarity = 1 - distance / maxLength;
+            if (similarity > 0.5 && similarity < 1.0) {
+                // Not exact match but similar
+                suggestions.push({ text: entity.name, similarity });
+            }
+        }
+        // Check entity types
+        const uniqueTypes = [...new Set(graph.entities.map(e => e.entityType))];
+        for (const type of uniqueTypes) {
+            const distance = levenshteinDistance(queryLower, type.toLowerCase());
+            const maxLength = Math.max(queryLower.length, type.length);
+            const similarity = 1 - distance / maxLength;
+            if (similarity > 0.5 && similarity < 1.0) {
+                suggestions.push({ text: type, similarity });
+            }
+        }
+        // Sort by similarity and return top suggestions
+        return suggestions
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, maxSuggestions)
+            .map(s => s.text);
+    }
+}

package/dist/search/TFIDFIndexManager.js

@@ -0,0 +1,217 @@
+/**
+ * TF-IDF Index Manager
+ *
+ * Manages pre-calculated TF-IDF indexes for fast ranked search.
+ * Handles index building, incremental updates, and persistence.
+ *
+ * @module search/TFIDFIndexManager
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { calculateIDF, tokenize } from '../utils/tfidf.js';
+const INDEX_VERSION = '1.0';
+const INDEX_FILENAME = 'tfidf-index.json';
+/**
+ * Manages TF-IDF index lifecycle: building, updating, and persistence.
+ */
+export class TFIDFIndexManager {
+    indexPath;
+    index = null;
+    constructor(storageDir) {
+        this.indexPath = path.join(storageDir, '.indexes', INDEX_FILENAME);
+    }
+    /**
+     * Build a complete TF-IDF index from a knowledge graph.
+     *
+     * @param graph - Knowledge graph to index
+     * @returns Newly built TF-IDF index
+     */
+    async buildIndex(graph) {
+        const documents = new Map();
+        const allDocumentTexts = [];
+        const allTokens = [];
+        // Build document vectors
+        for (const entity of graph.entities) {
+            const documentText = [
+                entity.name,
+                entity.entityType,
+                ...entity.observations,
+            ].join(' ');
+            allDocumentTexts.push(documentText);
+            const tokens = tokenize(documentText);
+            allTokens.push(tokens);
+            // Calculate term frequencies
+            const termFreq = {};
+            for (const term of tokens) {
+                termFreq[term] = (termFreq[term] || 0) + 1;
+            }
+            documents.set(entity.name, {
+                entityName: entity.name,
+                terms: termFreq,
+                documentText,
+            });
+        }
+        // Calculate IDF for all terms
+        const idf = new Map();
+        const allTerms = new Set(allTokens.flat());
+        for (const term of allTerms) {
+            const idfScore = calculateIDF(term, allDocumentTexts);
+            idf.set(term, idfScore);
+        }
+        this.index = {
+            version: INDEX_VERSION,
+            lastUpdated: new Date().toISOString(),
+            documents,
+            idf,
+        };
+        return this.index;
+    }
+    /**
+     * Update the index incrementally when entities change.
+     *
+     * More efficient than rebuilding the entire index.
+     *
+     * @param graph - Updated knowledge graph
+     * @param changedEntityNames - Names of entities that changed
+     */
+    async updateIndex(graph, changedEntityNames) {
+        if (!this.index) {
+            // No existing index, build from scratch
+            return this.buildIndex(graph);
+        }
+        // Rebuild document vectors for changed entities
+        const allDocumentTexts = [];
+        const allTokens = [];
+        const updatedDocuments = new Map(this.index.documents);
+        // Remove deleted entities
+        for (const entityName of changedEntityNames) {
+            const entity = graph.entities.find(e => e.name === entityName);
+            if (!entity) {
+                updatedDocuments.delete(entityName);
+            }
+        }
+        // Update/add changed entities
+        for (const entity of graph.entities) {
+            const documentText = [
+                entity.name,
+                entity.entityType,
+                ...entity.observations,
+            ].join(' ');
+            allDocumentTexts.push(documentText);
+            const tokens = tokenize(documentText);
+            allTokens.push(tokens);
+            if (changedEntityNames.has(entity.name)) {
+                // Calculate term frequencies for changed entity
+                const termFreq = {};
+                for (const term of tokens) {
+                    termFreq[term] = (termFreq[term] || 0) + 1;
+                }
+                updatedDocuments.set(entity.name, {
+                    entityName: entity.name,
+                    terms: termFreq,
+                    documentText,
+                });
+            }
+        }
+        // Recalculate IDF (need all documents for accurate IDF)
+        const idf = new Map();
+        const allTerms = new Set(allTokens.flat());
+        for (const term of allTerms) {
+            const idfScore = calculateIDF(term, allDocumentTexts);
+            idf.set(term, idfScore);
+        }
+        this.index = {
+            version: INDEX_VERSION,
+            lastUpdated: new Date().toISOString(),
+            documents: updatedDocuments,
+            idf,
+        };
+        return this.index;
+    }
+    /**
+     * Load index from disk.
+     *
+     * @returns Loaded index or null if not found
+     */
+    async loadIndex() {
+        try {
+            const data = await fs.readFile(this.indexPath, 'utf-8');
+            const serialized = JSON.parse(data);
+            this.index = {
+                version: serialized.version,
+                lastUpdated: serialized.lastUpdated,
+                documents: new Map(serialized.documents),
+                idf: new Map(serialized.idf),
+            };
+            return this.index;
+        }
+        catch (error) {
+            // Index doesn't exist or is invalid
+            return null;
+        }
+    }
+    /**
+     * Save index to disk.
+     *
+     * @param index - Index to save (uses cached index if not provided)
+     */
+    async saveIndex(index) {
+        const indexToSave = index || this.index;
+        if (!indexToSave) {
+            throw new Error('No index to save');
+        }
+        // Ensure index directory exists
+        const indexDir = path.dirname(this.indexPath);
+        await fs.mkdir(indexDir, { recursive: true });
+        // Serialize Map objects to arrays for JSON
+        const serialized = {
+            version: indexToSave.version,
+            lastUpdated: indexToSave.lastUpdated,
+            documents: Array.from(indexToSave.documents.entries()),
+            idf: Array.from(indexToSave.idf.entries()),
+        };
+        await fs.writeFile(this.indexPath, JSON.stringify(serialized, null, 2), 'utf-8');
+    }
+    /**
+     * Get the current cached index.
+     *
+     * @returns Cached index or null if not loaded
+     */
+    getIndex() {
+        return this.index;
+    }
+    /**
+     * Clear the cached index and delete from disk.
+     */
+    async clearIndex() {
+        this.index = null;
+        try {
+            await fs.unlink(this.indexPath);
+        }
+        catch {
+            // Index file doesn't exist, nothing to delete
+        }
+    }
+    /**
+     * Check if the index needs rebuilding based on graph state.
+     *
+     * @param graph - Current knowledge graph
+     * @returns True if index should be rebuilt
+     */
+    needsRebuild(graph) {
+        if (!this.index) {
+            return true;
+        }
+        // Check if entity count matches
+        if (this.index.documents.size !== graph.entities.length) {
+            return true;
+        }
+        // Check if all entities are in index
+        for (const entity of graph.entities) {
+            if (!this.index.documents.has(entity.name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/search/index.js

@@ -0,0 +1,14 @@
+/**
+ * Search Module Barrel Export
+ *
+ * Sprint 2: Added SearchFilterChain for centralized filter logic
+ */
+export { BasicSearch } from './BasicSearch.js';
+export { RankedSearch } from './RankedSearch.js';
+export { BooleanSearch } from './BooleanSearch.js';
+export { FuzzySearch } from './FuzzySearch.js';
+export { SearchSuggestions } from './SearchSuggestions.js';
+export { SavedSearchManager } from './SavedSearchManager.js';
+export { SearchManager } from './SearchManager.js';
+// Sprint 2: Search Filter Chain utilities
+export { SearchFilterChain } from './SearchFilterChain.js';

package/dist/server/MCPServer.js

@@ -0,0 +1,52 @@
+/**
+ * MCP Server
+ *
+ * Handles Model Context Protocol server initialization and tool registration.
+ * Tool definitions and handlers are extracted to separate modules for maintainability.
+ *
+ * @module server/MCPServer
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { logger } from '../utils/logger.js';
+import { toolDefinitions } from './toolDefinitions.js';
+import { handleToolCall } from './toolHandlers.js';
+/**
+ * MCP Server for Knowledge Graph operations.
+ * Exposes tools for entity/relation management, search, and analysis.
+ */
+export class MCPServer {
+    server;
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+        this.server = new Server({
+            name: "memory-server",
+            version: "0.8.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.registerToolHandlers();
+    }
+    registerToolHandlers() {
+        // Register list tools handler
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: toolDefinitions,
+            };
+        });
+        // Register call tool handler
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            return handleToolCall(name, args || {}, this.manager);
+        });
+    }
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        logger.info('Knowledge Graph MCP Server running on stdio');
+    }
+}