@danielsimonjr/memory-mcp 0.7.2 → 0.47.1

package/dist/utils/filterUtils.js

@@ -0,0 +1,155 @@
+/**
+ * Entity Filtering Utilities
+ *
+ * Centralizes common filtering logic for importance, date ranges, and other
+ * entity properties to eliminate duplicate patterns across search implementations.
+ */
+/**
+ * Checks if an entity's importance is within the specified range.
+ * Entities without importance are treated as not matching if any filter is set.
+ *
+ * @param importance - The entity's importance value (may be undefined)
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns true if importance is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * // Check if entity passes importance filter
+ * if (isWithinImportanceRange(entity.importance, 5, 10)) {
+ *   // Entity has importance between 5 and 10
+ * }
+ * ```
+ */
+export function isWithinImportanceRange(importance, minImportance, maxImportance) {
+    // If no filters set, always pass
+    if (minImportance === undefined && maxImportance === undefined) {
+        return true;
+    }
+    // Check minimum importance
+    if (minImportance !== undefined) {
+        if (importance === undefined || importance < minImportance) {
+            return false;
+        }
+    }
+    // Check maximum importance
+    if (maxImportance !== undefined) {
+        if (importance === undefined || importance > maxImportance) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Filters entities by importance range.
+ * Returns all entities if no importance filters are specified.
+ *
+ * @param entities - Array of entities to filter
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns Filtered entities within the importance range
+ */
+export function filterByImportance(entities, minImportance, maxImportance) {
+    if (minImportance === undefined && maxImportance === undefined) {
+        return entities;
+    }
+    return entities.filter(e => isWithinImportanceRange(e.importance, minImportance, maxImportance));
+}
+/**
+ * Checks if a date value is within the specified range.
+ * Handles undefined values appropriately.
+ *
+ * @param dateValue - ISO 8601 date string to check (may be undefined)
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns true if date is within range or no filters are set
+ */
+export function isWithinDateRange(dateValue, startDate, endDate) {
+    // If no filters set, always pass
+    if (!startDate && !endDate) {
+        return true;
+    }
+    // If date value is undefined but we have filters, fail
+    if (!dateValue) {
+        return false;
+    }
+    const date = new Date(dateValue);
+    if (startDate && date < new Date(startDate)) {
+        return false;
+    }
+    if (endDate && date > new Date(endDate)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Filters entities by creation date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities created within the date range
+ */
+export function filterByCreatedDate(entities, startDate, endDate) {
+    if (!startDate && !endDate) {
+        return entities;
+    }
+    return entities.filter(e => isWithinDateRange(e.createdAt, startDate, endDate));
+}
+/**
+ * Filters entities by last modified date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities modified within the date range
+ */
+export function filterByModifiedDate(entities, startDate, endDate) {
+    if (!startDate && !endDate) {
+        return entities;
+    }
+    return entities.filter(e => isWithinDateRange(e.lastModified, startDate, endDate));
+}
+/**
+ * Filters entities by entity type.
+ *
+ * @param entities - Array of entities to filter
+ * @param entityType - Entity type to filter by (case-sensitive)
+ * @returns Filtered entities of the specified type
+ */
+export function filterByEntityType(entities, entityType) {
+    if (!entityType) {
+        return entities;
+    }
+    return entities.filter(e => e.entityType === entityType);
+}
+/**
+ * Checks if an entity passes all the specified filters.
+ * Short-circuits on first failing filter for performance.
+ *
+ * Note: Tag filtering should be handled separately using tagUtils.hasMatchingTag
+ * as it requires special normalization logic.
+ *
+ * @param entity - Entity to check
+ * @param filters - Filters to apply
+ * @returns true if entity passes all filters
+ */
+export function entityPassesFilters(entity, filters) {
+    // 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 (!isWithinDateRange(entity.createdAt, filters.createdAfter, filters.createdBefore)) {
+        return false;
+    }
+    // Modified date filter
+    if (!isWithinDateRange(entity.lastModified, filters.modifiedAfter, filters.modifiedBefore)) {
+        return false;
+    }
+    return true;
+}

package/dist/utils/index.js

@@ -0,0 +1,39 @@
+/**
+ * Utilities Module Barrel Export
+ *
+ * Centralizes all utility exports for convenient importing.
+ * Sprint 1 additions: responseFormatter, tagUtils, entityUtils,
+ * validationHelper, paginationUtils, filterUtils
+ */
+// Error types
+export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, } from './errors.js';
+// String utilities
+export { levenshteinDistance } from './levenshtein.js';
+export { calculateTF, calculateIDF, calculateTFIDF, tokenize } from './tfidf.js';
+// Logging
+export { logger } from './logger.js';
+// Date utilities
+export { isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp } from './dateUtils.js';
+// Validation utilities
+export { validateEntity, validateRelation, validateImportance, validateTags } from './validationUtils.js';
+// Path utilities
+export { defaultMemoryPath, ensureMemoryFilePath, validateFilePath } from './pathUtils.js';
+// Constants
+export { FILE_EXTENSIONS, FILE_SUFFIXES, DEFAULT_FILE_NAMES, ENV_VARS, DEFAULT_BASE_DIR, LOG_PREFIXES, SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS, IMPORTANCE_RANGE, } from './constants.js';
+// Zod schemas
+export { EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, } from './schemas.js';
+// Search cache
+export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, } from './searchCache.js';
+// === Sprint 1: New Utility Exports ===
+// MCP Response formatting (Task 1.1)
+export { formatToolResponse, formatTextResponse, formatRawResponse, formatErrorResponse, } from './responseFormatter.js';
+// Tag utilities (Task 1.2)
+export { normalizeTag, normalizeTags, hasMatchingTag, hasAllTags, filterByTags, addUniqueTags, removeTags, } from './tagUtils.js';
+// Entity utilities (Task 1.3)
+export { findEntityByName, findEntitiesByNames, entityExists, getEntityIndex, removeEntityByName, getEntityNameSet, groupEntitiesByType, touchEntity, } from './entityUtils.js';
+// Zod validation helpers (Task 1.4)
+export { formatZodErrors, validateWithSchema, validateSafe, validateArrayWithSchema, } from './validationHelper.js';
+// Pagination utilities (Task 1.5)
+export { validatePagination, applyPagination, paginateArray, getPaginationMeta, } from './paginationUtils.js';
+// Filter utilities (Task 1.6)
+export { isWithinImportanceRange, filterByImportance, filterByCreatedDate, filterByModifiedDate, filterByEntityType, entityPassesFilters, } from './filterUtils.js';

package/dist/utils/levenshtein.js

@@ -0,0 +1,62 @@
+/**
+ * Levenshtein Distance Algorithm
+ *
+ * Calculates the minimum number of single-character edits (insertions,
+ * deletions, or substitutions) needed to change one string into another.
+ *
+ * Used for fuzzy string matching to find similar entities despite typos.
+ *
+ * @module utils/levenshtein
+ */
+/**
+ * Calculate Levenshtein distance between two strings.
+ *
+ * Returns the minimum number of single-character edits needed to change
+ * one word into another.
+ *
+ * **Algorithm**: Dynamic programming with O(m*n) time and space complexity,
+ * where m and n are the lengths of the two strings.
+ *
+ * @param str1 - First string to compare
+ * @param str2 - Second string to compare
+ * @returns Minimum number of edits required (0 = identical strings)
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance("kitten", "sitting"); // Returns 3
+ * levenshteinDistance("hello", "hello");    // Returns 0
+ * levenshteinDistance("abc", "");           // Returns 3
+ * ```
+ */
+export function levenshteinDistance(str1, str2) {
+    const m = str1.length;
+    const n = str2.length;
+    // Create 2D array for dynamic programming
+    const dp = Array(m + 1)
+        .fill(null)
+        .map(() => Array(n + 1).fill(0));
+    // Initialize base cases: distance from empty string
+    for (let i = 0; i <= m; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= n; j++) {
+        dp[0][j] = j;
+    }
+    // Fill dp table
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (str1[i - 1] === str2[j - 1]) {
+                // Characters match, no edit needed
+                dp[i][j] = dp[i - 1][j - 1];
+            }
+            else {
+                // Take minimum of three operations
+                dp[i][j] = Math.min(dp[i - 1][j] + 1, // deletion
+                dp[i][j - 1] + 1, // insertion
+                dp[i - 1][j - 1] + 1 // substitution
+                );
+            }
+        }
+    }
+    return dp[m][n];
+}

package/dist/utils/logger.js

@@ -0,0 +1,33 @@
+/**
+ * Simple logging utility for the Memory MCP Server
+ *
+ * Provides consistent log formatting with levels: debug, info, warn, error
+ */
+export const logger = {
+    /**
+     * Debug level logging (verbose, for development)
+     */
+    debug: (msg, ...args) => {
+        if (process.env.LOG_LEVEL === 'debug') {
+            console.debug(`[DEBUG] ${msg}`, ...args);
+        }
+    },
+    /**
+     * Info level logging (general informational messages)
+     */
+    info: (msg, ...args) => {
+        console.log(`[INFO] ${msg}`, ...args);
+    },
+    /**
+     * Warning level logging (warnings that don't prevent operation)
+     */
+    warn: (msg, ...args) => {
+        console.warn(`[WARN] ${msg}`, ...args);
+    },
+    /**
+     * Error level logging (errors that affect functionality)
+     */
+    error: (msg, ...args) => {
+        console.error(`[ERROR] ${msg}`, ...args);
+    },
+};

package/dist/utils/paginationUtils.js

@@ -0,0 +1,81 @@
+/**
+ * Pagination Utilities
+ *
+ * Centralizes pagination validation and application logic
+ * to eliminate duplicate patterns across search implementations.
+ */
+import { SEARCH_LIMITS } from './constants.js';
+/**
+ * Validates and normalizes pagination parameters.
+ * Ensures offset is non-negative and limit is within configured bounds.
+ *
+ * @param offset - Starting position (default: 0)
+ * @param limit - Maximum results to return (default: SEARCH_LIMITS.DEFAULT)
+ * @returns Validated pagination parameters with helper methods
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(10, 50);
+ * const results = items.slice(pagination.offset, pagination.offset + pagination.limit);
+ * if (pagination.hasMore(items.length)) {
+ *   console.log('More results available');
+ * }
+ * ```
+ */
+export function validatePagination(offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const validatedOffset = Math.max(0, offset);
+    const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+    return {
+        offset: validatedOffset,
+        limit: validatedLimit,
+        hasMore: (totalCount) => validatedOffset + validatedLimit < totalCount,
+    };
+}
+/**
+ * Applies pagination to an array of items.
+ *
+ * @param items - Array to paginate
+ * @param pagination - Validated pagination parameters
+ * @returns Paginated slice of the array
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(offset, limit);
+ * const pageResults = applyPagination(allResults, pagination);
+ * ```
+ */
+export function applyPagination(items, pagination) {
+    return items.slice(pagination.offset, pagination.offset + pagination.limit);
+}
+/**
+ * Applies pagination using raw offset and limit values.
+ * Combines validation and application in one call.
+ *
+ * @param items - Array to paginate
+ * @param offset - Starting position
+ * @param limit - Maximum results
+ * @returns Paginated slice of the array
+ */
+export function paginateArray(items, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const pagination = validatePagination(offset, limit);
+    return applyPagination(items, pagination);
+}
+/**
+ * Calculates pagination metadata for a result set.
+ *
+ * @param totalCount - Total number of items
+ * @param offset - Current offset
+ * @param limit - Current limit
+ * @returns Pagination metadata
+ */
+export function getPaginationMeta(totalCount, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const pagination = validatePagination(offset, limit);
+    return {
+        totalCount,
+        offset: pagination.offset,
+        limit: pagination.limit,
+        hasMore: pagination.hasMore(totalCount),
+        pageNumber: Math.floor(pagination.offset / pagination.limit) + 1,
+        totalPages: Math.ceil(totalCount / pagination.limit),
+    };
+}

package/dist/utils/pathUtils.js

@@ -0,0 +1,115 @@
+/**
+ * Path Utilities
+ *
+ * Helper functions for file path management and backward compatibility.
+ * Handles memory file path resolution with environment variable support.
+ *
+ * @module utils/pathUtils
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { FileOperationError } from './errors.js';
+/**
+ * Validate and normalize a file path to prevent path traversal attacks.
+ *
+ * This function:
+ * - Normalizes the path to canonical form
+ * - Converts relative paths to absolute paths
+ * - Detects and prevents path traversal attempts (..)
+ *
+ * @param filePath - The file path to validate
+ * @param baseDir - Optional base directory for relative paths (defaults to process.cwd())
+ * @returns Validated absolute file path
+ * @throws {FileOperationError} If path traversal is detected or path is invalid
+ *
+ * @example
+ * ```typescript
+ * // Valid paths
+ * validateFilePath('/var/data/memory.jsonl'); // Returns absolute path
+ * validateFilePath('data/memory.jsonl'); // Returns absolute path from cwd
+ *
+ * // Invalid paths (throws FileOperationError)
+ * validateFilePath('../../../etc/passwd'); // Path traversal detected
+ * validateFilePath('/var/data/../../../etc/passwd'); // Path traversal detected
+ * ```
+ */
+export function validateFilePath(filePath, baseDir = process.cwd()) {
+    // Normalize path to remove redundant separators and resolve . and ..
+    const normalized = path.normalize(filePath);
+    // Convert to absolute path
+    const absolute = path.isAbsolute(normalized)
+        ? normalized
+        : path.join(baseDir, normalized);
+    // After normalization, check if path still contains .. which would indicate
+    // traversal beyond the base directory
+    const finalNormalized = path.normalize(absolute);
+    // Split path into segments and check for suspicious patterns
+    const segments = finalNormalized.split(path.sep);
+    if (segments.includes('..')) {
+        throw new FileOperationError(`Path traversal detected in file path: ${filePath}`, filePath);
+    }
+    return finalNormalized;
+}
+/**
+ * Default memory file path (in same directory as compiled code).
+ */
+export const defaultMemoryPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../memory.jsonl');
+/**
+ * Ensure memory file path with backward compatibility migration.
+ *
+ * Handles:
+ * 1. Custom MEMORY_FILE_PATH environment variable (with path traversal protection)
+ * 2. Backward compatibility: migrates memory.json to memory.jsonl
+ * 3. Absolute vs relative path resolution
+ *
+ * @returns Resolved and validated memory file path
+ * @throws {FileOperationError} If path traversal is detected in MEMORY_FILE_PATH
+ *
+ * @example
+ * ```typescript
+ * // Use environment variable
+ * process.env.MEMORY_FILE_PATH = '/data/memory.jsonl';
+ * const path = await ensureMemoryFilePath(); // '/data/memory.jsonl'
+ *
+ * // Use default path
+ * delete process.env.MEMORY_FILE_PATH;
+ * const path = await ensureMemoryFilePath(); // './memory.jsonl'
+ *
+ * // Invalid path (throws error)
+ * process.env.MEMORY_FILE_PATH = '../../../etc/passwd';
+ * await ensureMemoryFilePath(); // Throws FileOperationError
+ * ```
+ */
+export async function ensureMemoryFilePath() {
+    if (process.env.MEMORY_FILE_PATH) {
+        // Custom path provided, validate and resolve to absolute
+        const baseDir = path.dirname(fileURLToPath(import.meta.url)) + '/../';
+        const validatedPath = validateFilePath(process.env.MEMORY_FILE_PATH, baseDir);
+        return validatedPath;
+    }
+    // No custom path set, check for backward compatibility migration
+    const oldMemoryPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../memory.json');
+    const newMemoryPath = defaultMemoryPath;
+    try {
+        // Check if old file exists
+        await fs.access(oldMemoryPath);
+        try {
+            // Check if new file exists
+            await fs.access(newMemoryPath);
+            // Both files exist, use new one (no migration needed)
+            return newMemoryPath;
+        }
+        catch {
+            // Old file exists, new file doesn't - migrate
+            console.log('[INFO] Found legacy memory.json file, migrating to memory.jsonl for JSONL format compatibility');
+            await fs.rename(oldMemoryPath, newMemoryPath);
+            console.log('[INFO] Successfully migrated memory.json to memory.jsonl');
+            return newMemoryPath;
+        }
+    }
+    catch {
+        // Old file doesn't exist, use new path
+        return newMemoryPath;
+    }
+}

package/dist/utils/responseFormatter.js

@@ -0,0 +1,55 @@
+/**
+ * MCP Tool Response Formatter Utilities
+ *
+ * Centralizes response formatting for MCP tool calls to eliminate
+ * redundant JSON.stringify patterns across the codebase.
+ */
+/**
+ * Formats data as an MCP tool response with JSON content.
+ * Centralizes the response format to ensure consistency and reduce duplication.
+ *
+ * @param data - Any data to be JSON stringified
+ * @returns Formatted MCP tool response
+ */
+export function formatToolResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Formats a simple text message as an MCP tool response.
+ * Use for success messages that don't need JSON formatting.
+ *
+ * @param message - Plain text message
+ * @returns Formatted MCP tool response
+ */
+export function formatTextResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+/**
+ * Formats raw string content as an MCP tool response.
+ * Use for export formats that return pre-formatted strings (markdown, CSV, etc.)
+ *
+ * @param content - Raw string content
+ * @returns Formatted MCP tool response
+ */
+export function formatRawResponse(content) {
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}
+/**
+ * Formats an error as an MCP tool response with isError flag.
+ *
+ * @param error - Error object or message string
+ * @returns Formatted MCP tool error response
+ */
+export function formatErrorResponse(error) {
+    const message = error instanceof Error ? error.message : error;
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}