@danielsimonjr/memory-mcp 0.7.1 → 0.41.0

package/dist/types/analytics.types.js

@@ -0,0 +1,6 @@
+/**
+ * Analytics Types
+ *
+ * Type definitions for graph statistics, validation reports, and analytics data.
+ */
+export {};

package/dist/types/entity.types.js

@@ -0,0 +1,7 @@
+/**
+ * Entity Types
+ *
+ * Core type definitions for entities, relations, and the knowledge graph structure.
+ * These types form the foundation of the memory MCP server's data model.
+ */
+export {};

package/dist/types/import-export.types.js

@@ -0,0 +1,7 @@
+/**
+ * Import/Export Types
+ *
+ * Type definitions for import and export operations, including
+ * result summaries and compression results.
+ */
+export {};

package/dist/types/index.js

@@ -0,0 +1,12 @@
+/**
+ * Types Module - Barrel Export
+ *
+ * Central export point for all type definitions used throughout the
+ * Memory MCP Server. Import from this file to access any type.
+ *
+ * @example
+ * ```typescript
+ * import { Entity, Relation, KnowledgeGraph, SearchResult } from './types/index.js';
+ * ```
+ */
+export {};

package/dist/types/search.types.js

@@ -0,0 +1,7 @@
+/**
+ * Search Types
+ *
+ * Type definitions for search operations, including search results,
+ * saved searches, and boolean query AST structures.
+ */
+export {};

package/dist/types/tag.types.js

@@ -0,0 +1,6 @@
+/**
+ * Tag Types
+ *
+ * Type definitions for tag management, including tag aliases for synonyms.
+ */
+export {};

package/dist/utils/constants.js

@@ -0,0 +1,127 @@
+/**
+ * Application Constants
+ *
+ * Centralized configuration constants for file paths, extensions, and default values.
+ *
+ * @module utils/constants
+ */
+/**
+ * File extensions used by the memory system.
+ */
+export const FILE_EXTENSIONS = {
+    /** JSONL format for line-delimited JSON storage */
+    JSONL: '.jsonl',
+    /** Legacy JSON format (backward compatibility) */
+    JSON: '.json',
+};
+/**
+ * File name suffixes for auxiliary data files.
+ * These suffixes are appended to the base memory file name.
+ */
+export const FILE_SUFFIXES = {
+    /** Suffix for saved searches file */
+    SAVED_SEARCHES: '-saved-searches',
+    /** Suffix for tag aliases file */
+    TAG_ALIASES: '-tag-aliases',
+};
+/**
+ * Default file names used by the memory system.
+ */
+export const DEFAULT_FILE_NAMES = {
+    /** Default memory file name */
+    MEMORY: 'memory',
+    /** Legacy memory file name (for backward compatibility) */
+    MEMORY_LEGACY: 'memory',
+};
+/**
+ * Environment variable names used for configuration.
+ */
+export const ENV_VARS = {
+    /** Environment variable for custom memory file path */
+    MEMORY_FILE_PATH: 'MEMORY_FILE_PATH',
+};
+/**
+ * Default base directory relative to the compiled code.
+ */
+export const DEFAULT_BASE_DIR = '../';
+/**
+ * Log message prefixes for consistent logging.
+ */
+export const LOG_PREFIXES = {
+    /** Informational message prefix */
+    INFO: '[INFO]',
+    /** Error message prefix */
+    ERROR: '[ERROR]',
+    /** Warning message prefix */
+    WARN: '[WARN]',
+};
+/**
+ * Similarity scoring weights for duplicate detection.
+ * These weights determine the relative importance of each factor
+ * when calculating entity similarity for duplicate detection.
+ */
+export const SIMILARITY_WEIGHTS = {
+    /** Name similarity weight (40%) - Uses Levenshtein distance */
+    NAME: 0.4,
+    /** Entity type match weight (20%) - Exact match required */
+    TYPE: 0.2,
+    /** Observation overlap weight (30%) - Uses Jaccard similarity */
+    OBSERVATION: 0.3,
+    /** Tag overlap weight (10%) - Uses Jaccard similarity */
+    TAG: 0.1,
+};
+/**
+ * Default threshold for duplicate detection (80% similarity required).
+ */
+export const DEFAULT_DUPLICATE_THRESHOLD = 0.8;
+/**
+ * Search result limits to prevent resource exhaustion.
+ */
+export const SEARCH_LIMITS = {
+    /** Default number of results to return */
+    DEFAULT: 50,
+    /** Maximum number of results allowed */
+    MAX: 200,
+    /** Minimum number of results (must be at least 1) */
+    MIN: 1,
+};
+/**
+ * Entity importance range validation constants.
+ * Importance is used to prioritize entities (0 = lowest, 10 = highest).
+ */
+export const IMPORTANCE_RANGE = {
+    /** Minimum importance value */
+    MIN: 0,
+    /** Maximum importance value */
+    MAX: 10,
+};
+/**
+ * Graph size limits to prevent resource exhaustion and ensure performance.
+ * These limits help maintain system stability and responsiveness.
+ */
+export const GRAPH_LIMITS = {
+    /** Maximum number of entities in the graph */
+    MAX_ENTITIES: 100000,
+    /** Maximum number of relations in the graph */
+    MAX_RELATIONS: 1000000,
+    /** Maximum graph file size in megabytes */
+    MAX_FILE_SIZE_MB: 500,
+    /** Maximum observations per entity */
+    MAX_OBSERVATIONS_PER_ENTITY: 1000,
+    /** Maximum tags per entity */
+    MAX_TAGS_PER_ENTITY: 100,
+};
+/**
+ * Query complexity limits to prevent expensive query operations.
+ * These limits protect against denial-of-service through complex queries.
+ */
+export const QUERY_LIMITS = {
+    /** Maximum nesting depth for boolean queries */
+    MAX_DEPTH: 10,
+    /** Maximum number of terms in a single query */
+    MAX_TERMS: 50,
+    /** Maximum number of boolean operators (AND/OR/NOT) */
+    MAX_OPERATORS: 20,
+    /** Maximum query string length */
+    MAX_QUERY_LENGTH: 5000,
+};

package/dist/utils/dateUtils.js

@@ -0,0 +1,89 @@
+/**
+ * Date Utilities
+ *
+ * Helper functions for date parsing, validation, and range filtering.
+ * All dates use ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ).
+ *
+ * @module utils/dateUtils
+ */
+/**
+ * Check if a date falls within a specified range.
+ *
+ * @param date - ISO 8601 date string to check
+ * @param start - Optional start date (inclusive)
+ * @param end - Optional end date (inclusive)
+ * @returns True if date is within range
+ *
+ * @example
+ * ```typescript
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'); // true
+ * isWithinDateRange('2024-06-15T00:00:00Z', '2024-07-01T00:00:00Z'); // false
+ * ```
+ */
+export function isWithinDateRange(date, start, end) {
+    const dateObj = new Date(date);
+    if (isNaN(dateObj.getTime())) {
+        return false;
+    }
+    if (start) {
+        const startObj = new Date(start);
+        if (isNaN(startObj.getTime())) {
+            return false;
+        }
+        if (dateObj < startObj) {
+            return false;
+        }
+    }
+    if (end) {
+        const endObj = new Date(end);
+        if (isNaN(endObj.getTime())) {
+            return false;
+        }
+        if (dateObj > endObj) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Parse and validate date range strings.
+ *
+ * @param startDate - Optional ISO 8601 start date
+ * @param endDate - Optional ISO 8601 end date
+ * @returns Parsed Date objects or null
+ */
+export function parseDateRange(startDate, endDate) {
+    let start = null;
+    let end = null;
+    if (startDate) {
+        start = new Date(startDate);
+        if (isNaN(start.getTime())) {
+            start = null;
+        }
+    }
+    if (endDate) {
+        end = new Date(endDate);
+        if (isNaN(end.getTime())) {
+            end = null;
+        }
+    }
+    return { start, end };
+}
+/**
+ * Validate if a string is a valid ISO 8601 date.
+ *
+ * @param date - Date string to validate
+ * @returns True if valid ISO 8601 date
+ */
+export function isValidISODate(date) {
+    const dateObj = new Date(date);
+    return !isNaN(dateObj.getTime()) && dateObj.toISOString() === date;
+}
+/**
+ * Get current timestamp in ISO 8601 format.
+ *
+ * @returns Current timestamp string
+ */
+export function getCurrentTimestamp() {
+    return new Date().toISOString();
+}

package/dist/utils/errors.js

@@ -0,0 +1,121 @@
+/**
+ * Custom Error Types
+ *
+ * Defines custom error classes for better error handling and debugging.
+ *
+ * @module utils/errors
+ */
+/**
+ * Base error class for all knowledge graph errors.
+ * Extends the native Error class with additional context.
+ */
+export class KnowledgeGraphError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'KnowledgeGraphError';
+        // Maintains proper stack trace in V8 engines
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when an entity is not found.
+ */
+export class EntityNotFoundError extends KnowledgeGraphError {
+    constructor(entityName) {
+        super(`Entity "${entityName}" not found`, 'ENTITY_NOT_FOUND');
+        this.name = 'EntityNotFoundError';
+    }
+}
+/**
+ * Error thrown when a relation is not found.
+ */
+export class RelationNotFoundError extends KnowledgeGraphError {
+    constructor(from, to, relationType) {
+        const desc = relationType
+            ? `Relation "${from}" --[${relationType}]--> "${to}"`
+            : `Relation from "${from}" to "${to}"`;
+        super(`${desc} not found`, 'RELATION_NOT_FOUND');
+        this.name = 'RelationNotFoundError';
+    }
+}
+/**
+ * Error thrown when attempting to create a duplicate entity.
+ */
+export class DuplicateEntityError extends KnowledgeGraphError {
+    constructor(entityName) {
+        super(`Entity "${entityName}" already exists`, 'DUPLICATE_ENTITY');
+        this.name = 'DuplicateEntityError';
+    }
+}
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends KnowledgeGraphError {
+    errors;
+    constructor(message, errors) {
+        super(message, 'VALIDATION_ERROR');
+        this.errors = errors;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Error thrown when a cycle is detected in hierarchies.
+ */
+export class CycleDetectedError extends KnowledgeGraphError {
+    constructor(entityName, parentName) {
+        super(`Setting parent "${parentName}" for entity "${entityName}" would create a cycle`, 'CYCLE_DETECTED');
+        this.name = 'CycleDetectedError';
+    }
+}
+/**
+ * Error thrown when an invalid importance value is provided.
+ */
+export class InvalidImportanceError extends KnowledgeGraphError {
+    constructor(value, min = 0, max = 10) {
+        super(`Importance must be between ${min} and ${max}, got ${value}`, 'INVALID_IMPORTANCE');
+        this.name = 'InvalidImportanceError';
+    }
+}
+/**
+ * Error thrown when a file operation fails.
+ */
+export class FileOperationError extends KnowledgeGraphError {
+    constructor(operation, filePath, cause) {
+        super(`Failed to ${operation} file: ${filePath}${cause ? ` - ${cause.message}` : ''}`, 'FILE_OPERATION_ERROR');
+        this.name = 'FileOperationError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Error thrown when an import operation fails.
+ */
+export class ImportError extends KnowledgeGraphError {
+    constructor(format, message) {
+        super(`Import failed (${format}): ${message}`, 'IMPORT_ERROR');
+        this.name = 'ImportError';
+    }
+}
+/**
+ * Error thrown when an export operation fails.
+ */
+export class ExportError extends KnowledgeGraphError {
+    constructor(format, message) {
+        super(`Export failed (${format}): ${message}`, 'EXPORT_ERROR');
+        this.name = 'ExportError';
+    }
+}
+/**
+ * Error thrown when insufficient entities are provided for an operation.
+ */
+export class InsufficientEntitiesError extends KnowledgeGraphError {
+    constructor(operation, required, provided) {
+        super(`${operation} requires at least ${required} entities, got ${provided}`, 'INSUFFICIENT_ENTITIES');
+        this.name = 'InsufficientEntitiesError';
+    }
+}

package/dist/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * Utilities Module Barrel Export
+ */
+export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, } from './errors.js';
+export { levenshteinDistance } from './levenshtein.js';
+export { calculateTF, calculateIDF, calculateTFIDF, tokenize } from './tfidf.js';
+export { logger } from './logger.js';
+export { isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp } from './dateUtils.js';
+export { validateEntity, validateRelation, validateImportance, validateTags } from './validationUtils.js';
+export { defaultMemoryPath, ensureMemoryFilePath, validateFilePath } from './pathUtils.js';
+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';
+export { EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, } from './schemas.js';
+export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, } from './searchCache.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/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;
+    }
+}