@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

package/dist/search/BasicSearch.js

@@ -0,0 +1,161 @@
+/**
+ * Basic Search
+ *
+ * Simple text-based search with tag, importance, and date filters with result caching.
+ *
+ * @module search/BasicSearch
+ */
+import { isWithinDateRange } from '../utils/dateUtils.js';
+import { SEARCH_LIMITS } from '../utils/constants.js';
+import { searchCaches } from '../utils/searchCache.js';
+/**
+ * Performs basic text search with optional filters and caching.
+ */
+export class BasicSearch {
+    storage;
+    enableCache;
+    constructor(storage, enableCache = true) {
+        this.storage = storage;
+        this.enableCache = enableCache;
+    }
+    /**
+     * Search nodes by text query with optional filters and pagination.
+     *
+     * Searches across entity names, types, and observations.
+     *
+     * @param query - Text to search for (case-insensitive)
+     * @param tags - Optional tags to filter by
+     * @param minImportance - Optional minimum importance (0-10)
+     * @param maxImportance - Optional maximum importance (0-10)
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    async searchNodes(query, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        // Check cache first
+        if (this.enableCache) {
+            const cacheKey = { query, tags, minImportance, maxImportance, offset, limit };
+            const cached = searchCaches.basic.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        const graph = await this.storage.loadGraph();
+        const normalizedTags = tags?.map(tag => tag.toLowerCase());
+        // Validate pagination parameters
+        const validatedOffset = Math.max(0, offset);
+        const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+        const filteredEntities = graph.entities.filter(e => {
+            // Text search
+            const matchesQuery = e.name.toLowerCase().includes(query.toLowerCase()) ||
+                e.entityType.toLowerCase().includes(query.toLowerCase()) ||
+                e.observations.some(o => o.toLowerCase().includes(query.toLowerCase()));
+            if (!matchesQuery)
+                return false;
+            // Tag filter
+            if (normalizedTags && normalizedTags.length > 0) {
+                if (!e.tags || e.tags.length === 0)
+                    return false;
+                const entityTags = e.tags.map(tag => tag.toLowerCase());
+                const hasMatchingTag = normalizedTags.some(tag => entityTags.includes(tag));
+                if (!hasMatchingTag)
+                    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;
+        });
+        // Apply pagination
+        const paginatedEntities = filteredEntities.slice(validatedOffset, validatedOffset + validatedLimit);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        const result = { entities: paginatedEntities, relations: filteredRelations };
+        // Cache the result
+        if (this.enableCache) {
+            const cacheKey = { query, tags, minImportance, maxImportance, offset, limit };
+            searchCaches.basic.set(cacheKey, result);
+        }
+        return result;
+    }
+    /**
+     * Open specific nodes by name.
+     *
+     * @param names - Array of entity names to retrieve
+     * @returns Knowledge graph with specified entities and their relations
+     */
+    async openNodes(names) {
+        const graph = await this.storage.loadGraph();
+        const filteredEntities = graph.entities.filter(e => names.includes(e.name));
+        const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        return { entities: filteredEntities, relations: filteredRelations };
+    }
+    /**
+     * Search by date range with optional filters and pagination.
+     *
+     * @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
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    async searchByDateRange(startDate, endDate, entityType, tags, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        // Check cache first
+        if (this.enableCache) {
+            const cacheKey = { method: 'dateRange', startDate, endDate, entityType, tags, offset, limit };
+            const cached = searchCaches.basic.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        const graph = await this.storage.loadGraph();
+        const normalizedTags = tags?.map(tag => tag.toLowerCase());
+        // Validate pagination parameters
+        const validatedOffset = Math.max(0, offset);
+        const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+        const filteredEntities = graph.entities.filter(e => {
+            // Date filter (use createdAt or lastModified)
+            const dateToCheck = e.createdAt || e.lastModified;
+            if (dateToCheck && !isWithinDateRange(dateToCheck, startDate, endDate)) {
+                return false;
+            }
+            // Entity type filter
+            if (entityType && e.entityType !== entityType) {
+                return false;
+            }
+            // Tags filter
+            if (normalizedTags && normalizedTags.length > 0) {
+                if (!e.tags || e.tags.length === 0)
+                    return false;
+                const entityTags = e.tags.map(tag => tag.toLowerCase());
+                const hasMatchingTag = normalizedTags.some(tag => entityTags.includes(tag));
+                if (!hasMatchingTag)
+                    return false;
+            }
+            return true;
+        });
+        // Apply pagination
+        const paginatedEntities = filteredEntities.slice(validatedOffset, validatedOffset + validatedLimit);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => {
+            const dateToCheck = r.createdAt || r.lastModified;
+            const inDateRange = !dateToCheck || isWithinDateRange(dateToCheck, startDate, endDate);
+            const involvesFilteredEntities = filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to);
+            return inDateRange && involvesFilteredEntities;
+        });
+        const result = { entities: paginatedEntities, relations: filteredRelations };
+        // Cache the result
+        if (this.enableCache) {
+            const cacheKey = { method: 'dateRange', startDate, endDate, entityType, tags, offset, limit };
+            searchCaches.basic.set(cacheKey, result);
+        }
+        return result;
+    }
+}

package/dist/search/BooleanSearch.js

@@ -0,0 +1,304 @@
+/**
+ * Boolean Search
+ *
+ * Advanced search with boolean operators (AND, OR, NOT) and field-specific queries.
+ *
+ * @module search/BooleanSearch
+ */
+import { SEARCH_LIMITS, QUERY_LIMITS } from '../utils/constants.js';
+import { ValidationError } from '../utils/errors.js';
+/**
+ * Performs boolean search with query parsing and AST evaluation.
+ */
+export class BooleanSearch {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Boolean search with support for AND, OR, NOT operators, field-specific queries, and pagination.
+     *
+     * Query syntax examples:
+     * - "alice AND programming" - Both terms must match
+     * - "type:person OR type:organization" - Either type matches
+     * - "NOT archived" - Exclude archived items
+     * - "name:alice AND (observation:coding OR observation:teaching)"
+     *
+     * @param query - Boolean query string
+     * @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 matching the boolean query with pagination applied
+     */
+    async booleanSearch(query, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        // Validate query length
+        if (query.length > QUERY_LIMITS.MAX_QUERY_LENGTH) {
+            throw new ValidationError('Query too long', [`Query length ${query.length} exceeds maximum of ${QUERY_LIMITS.MAX_QUERY_LENGTH} characters`]);
+        }
+        const graph = await this.storage.loadGraph();
+        // Parse the query into an AST
+        let queryAst;
+        try {
+            queryAst = this.parseBooleanQuery(query);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse boolean query: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Validate query complexity
+        this.validateQueryComplexity(queryAst);
+        const normalizedTags = tags?.map(tag => tag.toLowerCase());
+        // Validate pagination parameters
+        const validatedOffset = Math.max(0, offset);
+        const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+        // Filter entities
+        const filteredEntities = graph.entities.filter(e => {
+            // Evaluate boolean query
+            if (!this.evaluateBooleanQuery(queryAst, e)) {
+                return false;
+            }
+            // Apply tag filter
+            if (normalizedTags && normalizedTags.length > 0) {
+                if (!e.tags || e.tags.length === 0)
+                    return false;
+                const entityTags = e.tags.map(tag => tag.toLowerCase());
+                const hasMatchingTag = normalizedTags.some(tag => entityTags.includes(tag));
+                if (!hasMatchingTag)
+                    return false;
+            }
+            // Apply 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;
+        });
+        // Apply pagination
+        const paginatedEntities = filteredEntities.slice(validatedOffset, validatedOffset + validatedLimit);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        return { entities: paginatedEntities, relations: filteredRelations };
+    }
+    /**
+     * Tokenize a boolean query into tokens.
+     *
+     * Handles quoted strings, parentheses, and operators.
+     */
+    tokenizeBooleanQuery(query) {
+        const tokens = [];
+        let current = '';
+        let inQuotes = false;
+        for (let i = 0; i < query.length; i++) {
+            const char = query[i];
+            if (char === '"') {
+                if (inQuotes) {
+                    // End of quoted string
+                    tokens.push(current);
+                    current = '';
+                    inQuotes = false;
+                }
+                else {
+                    // Start of quoted string
+                    if (current.trim()) {
+                        tokens.push(current.trim());
+                        current = '';
+                    }
+                    inQuotes = true;
+                }
+            }
+            else if (!inQuotes && (char === '(' || char === ')')) {
+                // Parentheses are separate tokens
+                if (current.trim()) {
+                    tokens.push(current.trim());
+                    current = '';
+                }
+                tokens.push(char);
+            }
+            else if (!inQuotes && /\s/.test(char)) {
+                // Whitespace outside quotes
+                if (current.trim()) {
+                    tokens.push(current.trim());
+                    current = '';
+                }
+            }
+            else {
+                current += char;
+            }
+        }
+        if (current.trim()) {
+            tokens.push(current.trim());
+        }
+        return tokens;
+    }
+    /**
+     * Parse a boolean search query into an AST.
+     *
+     * Supports: AND, OR, NOT, parentheses, field-specific queries (field:value)
+     */
+    parseBooleanQuery(query) {
+        const tokens = this.tokenizeBooleanQuery(query);
+        let position = 0;
+        const peek = () => tokens[position];
+        const consume = () => tokens[position++];
+        // Parse OR expressions (lowest precedence)
+        const parseOr = () => {
+            let left = parseAnd();
+            while (peek()?.toUpperCase() === 'OR') {
+                consume(); // consume 'OR'
+                const right = parseAnd();
+                left = { type: 'OR', children: [left, right] };
+            }
+            return left;
+        };
+        // Parse AND expressions
+        const parseAnd = () => {
+            let left = parseNot();
+            while (peek() && peek()?.toUpperCase() !== 'OR' && peek() !== ')') {
+                // Implicit AND if next token is not OR or )
+                if (peek()?.toUpperCase() === 'AND') {
+                    consume(); // consume 'AND'
+                }
+                const right = parseNot();
+                left = { type: 'AND', children: [left, right] };
+            }
+            return left;
+        };
+        // Parse NOT expressions
+        const parseNot = () => {
+            if (peek()?.toUpperCase() === 'NOT') {
+                consume(); // consume 'NOT'
+                const child = parseNot();
+                return { type: 'NOT', child };
+            }
+            return parsePrimary();
+        };
+        // Parse primary expressions (terms, field queries, parentheses)
+        const parsePrimary = () => {
+            const token = peek();
+            if (!token) {
+                throw new Error('Unexpected end of query');
+            }
+            // Parentheses
+            if (token === '(') {
+                consume(); // consume '('
+                const node = parseOr();
+                if (consume() !== ')') {
+                    throw new Error('Expected closing parenthesis');
+                }
+                return node;
+            }
+            // Field-specific query (field:value)
+            if (token.includes(':')) {
+                consume();
+                const [field, ...valueParts] = token.split(':');
+                const value = valueParts.join(':'); // Handle colons in value
+                return { type: 'TERM', field: field.toLowerCase(), value: value.toLowerCase() };
+            }
+            // Regular term
+            consume();
+            return { type: 'TERM', value: token.toLowerCase() };
+        };
+        const result = parseOr();
+        // Check for unconsumed tokens
+        if (position < tokens.length) {
+            throw new Error(`Unexpected token: ${tokens[position]}`);
+        }
+        return result;
+    }
+    /**
+     * Evaluate a boolean query AST against an entity.
+     */
+    evaluateBooleanQuery(node, entity) {
+        switch (node.type) {
+            case 'AND':
+                return node.children.every(child => this.evaluateBooleanQuery(child, entity));
+            case 'OR':
+                return node.children.some(child => this.evaluateBooleanQuery(child, entity));
+            case 'NOT':
+                return !this.evaluateBooleanQuery(node.child, entity);
+            case 'TERM': {
+                const value = node.value;
+                // Field-specific search
+                if (node.field) {
+                    switch (node.field) {
+                        case 'name':
+                            return entity.name.toLowerCase().includes(value);
+                        case 'type':
+                        case 'entitytype':
+                            return entity.entityType.toLowerCase().includes(value);
+                        case 'observation':
+                        case 'observations':
+                            return entity.observations.some(obs => obs.toLowerCase().includes(value));
+                        case 'tag':
+                        case 'tags':
+                            return entity.tags ? entity.tags.some(tag => tag.toLowerCase().includes(value)) : false;
+                        default:
+                            // Unknown field, search all text fields
+                            return this.entityMatchesTerm(entity, value);
+                    }
+                }
+                // General search across all fields
+                return this.entityMatchesTerm(entity, value);
+            }
+        }
+    }
+    /**
+     * Check if entity matches a search term in any text field.
+     */
+    entityMatchesTerm(entity, term) {
+        const termLower = term.toLowerCase();
+        return (entity.name.toLowerCase().includes(termLower) ||
+            entity.entityType.toLowerCase().includes(termLower) ||
+            entity.observations.some(obs => obs.toLowerCase().includes(termLower)) ||
+            (entity.tags?.some(tag => tag.toLowerCase().includes(termLower)) || false));
+    }
+    /**
+     * Validate query complexity to prevent resource exhaustion.
+     * Checks nesting depth, term count, and operator count against configured limits.
+     */
+    validateQueryComplexity(node, depth = 0) {
+        // Check nesting depth
+        if (depth > QUERY_LIMITS.MAX_DEPTH) {
+            throw new ValidationError('Query too complex', [`Query nesting depth ${depth} exceeds maximum of ${QUERY_LIMITS.MAX_DEPTH}`]);
+        }
+        // Count terms and operators recursively
+        const complexity = this.calculateQueryComplexity(node);
+        if (complexity.terms > QUERY_LIMITS.MAX_TERMS) {
+            throw new ValidationError('Query too complex', [`Query has ${complexity.terms} terms, exceeds maximum of ${QUERY_LIMITS.MAX_TERMS}`]);
+        }
+        if (complexity.operators > QUERY_LIMITS.MAX_OPERATORS) {
+            throw new ValidationError('Query too complex', [`Query has ${complexity.operators} operators, exceeds maximum of ${QUERY_LIMITS.MAX_OPERATORS}`]);
+        }
+    }
+    /**
+     * Calculate query complexity metrics.
+     */
+    calculateQueryComplexity(node, depth = 0) {
+        switch (node.type) {
+            case 'AND':
+            case 'OR':
+                const childResults = node.children.map(child => this.calculateQueryComplexity(child, depth + 1));
+                return {
+                    terms: childResults.reduce((sum, r) => sum + r.terms, 0),
+                    operators: childResults.reduce((sum, r) => sum + r.operators, 1), // +1 for current operator
+                    maxDepth: Math.max(depth, ...childResults.map(r => r.maxDepth)),
+                };
+            case 'NOT':
+                const notResult = this.calculateQueryComplexity(node.child, depth + 1);
+                return {
+                    terms: notResult.terms,
+                    operators: notResult.operators + 1,
+                    maxDepth: Math.max(depth, notResult.maxDepth),
+                };
+            case 'TERM':
+                return {
+                    terms: 1,
+                    operators: 0,
+                    maxDepth: depth,
+                };
+        }
+    }
+}

package/dist/search/FuzzySearch.js

@@ -0,0 +1,115 @@
+/**
+ * Fuzzy Search
+ *
+ * Search with typo tolerance using Levenshtein distance similarity.
+ *
+ * @module search/FuzzySearch
+ */
+import { levenshteinDistance } from '../utils/levenshtein.js';
+import { SEARCH_LIMITS } from '../utils/constants.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 const DEFAULT_FUZZY_THRESHOLD = 0.7;
+/**
+ * Performs fuzzy search with configurable similarity threshold.
+ */
+export class FuzzySearch {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * 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).
+     *
+     * @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
+     */
+    async fuzzySearch(query, threshold = DEFAULT_FUZZY_THRESHOLD, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        const graph = await this.storage.loadGraph();
+        const normalizedTags = tags?.map(tag => tag.toLowerCase());
+        // Validate pagination parameters
+        const validatedOffset = Math.max(0, offset);
+        const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+        // Filter entities using fuzzy matching
+        const filteredEntities = graph.entities.filter(e => {
+            // Fuzzy text search
+            const matchesQuery = this.isFuzzyMatch(e.name, query, threshold) ||
+                this.isFuzzyMatch(e.entityType, query, threshold) ||
+                e.observations.some(o => 
+                // For observations, split into words and check each word
+                o
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .some(word => this.isFuzzyMatch(word, query, threshold)) ||
+                    // Also check if the observation contains the query
+                    this.isFuzzyMatch(o, query, threshold));
+            if (!matchesQuery)
+                return false;
+            // Tag filter
+            if (normalizedTags && normalizedTags.length > 0) {
+                if (!e.tags || e.tags.length === 0)
+                    return false;
+                const entityTags = e.tags.map(tag => tag.toLowerCase());
+                const hasMatchingTag = normalizedTags.some(tag => entityTags.includes(tag));
+                if (!hasMatchingTag)
+                    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;
+        });
+        // Apply pagination
+        const paginatedEntities = filteredEntities.slice(validatedOffset, validatedOffset + validatedLimit);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        return {
+            entities: paginatedEntities,
+            relations: filteredRelations,
+        };
+    }
+    /**
+     * Check if two strings match with fuzzy logic.
+     *
+     * Returns true if:
+     * - Strings are identical
+     * - One contains the other
+     * - Levenshtein similarity >= threshold
+     *
+     * @param str1 - First string
+     * @param str2 - Second string
+     * @param threshold - Similarity threshold (0.0 to 1.0)
+     * @returns True if strings match fuzzily
+     */
+    isFuzzyMatch(str1, str2, threshold = 0.7) {
+        const s1 = str1.toLowerCase();
+        const s2 = str2.toLowerCase();
+        // Exact match
+        if (s1 === s2)
+            return true;
+        // One contains the other
+        if (s1.includes(s2) || s2.includes(s1))
+            return true;
+        // Calculate similarity using Levenshtein distance
+        const distance = levenshteinDistance(s1, s2);
+        const maxLength = Math.max(s1.length, s2.length);
+        const similarity = 1 - distance / maxLength;
+        return similarity >= threshold;
+    }
+}