@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/utils/entityUtils.js

@@ -1,10 +1,19 @@
 /**
- * Entity Lookup and Utility Functions
+ * Entity Utilities
  *
- * Centralizes entity lookup patterns to eliminate redundant code across managers.
- * Provides type-safe entity finding with optional error throwing.
+ * Consolidated module for entity-related utilities including:
+ * - Entity lookup and manipulation functions
+ * - Tag normalization and matching
+ * - Date parsing and validation
+ * - Entity filtering by various criteria
+ * - Path utilities and validation
+ *
+ * @module utils/entityUtils
  */
-import { EntityNotFoundError } from './errors.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { EntityNotFoundError, FileOperationError } from './errors.js';
 export function findEntityByName(graph, name, throwIfNotFound = true) {
     const entity = graph.entities.find(e => e.name === name);
     if (!entity && throwIfNotFound) {
@@ -106,3 +115,424 @@ export function touchEntity(entity) {
     entity.lastModified = new Date().toISOString();
     return entity;
 }
+// ==================== Tag Normalization and Matching ====================
+/**
+ * Normalizes a single tag to lowercase and trimmed.
+ *
+ * @param tag - Tag to normalize
+ * @returns Normalized tag
+ */
+export function normalizeTag(tag) {
+    return tag.toLowerCase().trim();
+}
+/**
+ * Normalizes an array of tags to lowercase.
+ * Handles undefined/null input gracefully.
+ *
+ * @param tags - Array of tags to normalize, or undefined
+ * @returns Normalized tags array, or empty array if input is undefined/null
+ */
+export function normalizeTags(tags) {
+    if (!tags || tags.length === 0)
+        return [];
+    return tags.map(tag => tag.toLowerCase());
+}
+/**
+ * Checks if an entity's tags include any of the specified search tags.
+ * Both inputs are normalized before comparison.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param searchTags - Tags to search for (may be undefined)
+ * @returns true if any search tag matches any entity tag, false if no match or either is empty
+ */
+export function hasMatchingTag(entityTags, searchTags) {
+    if (!entityTags || entityTags.length === 0)
+        return false;
+    if (!searchTags || searchTags.length === 0)
+        return false;
+    const normalizedEntity = normalizeTags(entityTags);
+    const normalizedSearch = normalizeTags(searchTags);
+    return normalizedSearch.some(tag => normalizedEntity.includes(tag));
+}
+/**
+ * Checks if entity tags include ALL of the specified required tags.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param requiredTags - All tags that must be present
+ * @returns true if all required tags are present
+ */
+export function hasAllTags(entityTags, requiredTags) {
+    if (!entityTags || entityTags.length === 0)
+        return false;
+    if (requiredTags.length === 0)
+        return true;
+    const normalizedEntity = normalizeTags(entityTags);
+    return normalizeTags(requiredTags).every(tag => normalizedEntity.includes(tag));
+}
+/**
+ * Filters entities by tag match.
+ * Returns all entities if searchTags is empty or undefined.
+ *
+ * @param entities - Array of entities with optional tags property
+ * @param searchTags - Tags to filter by
+ * @returns Filtered entities that have at least one matching tag
+ */
+export function filterByTags(entities, searchTags) {
+    if (!searchTags || searchTags.length === 0) {
+        return entities;
+    }
+    const normalizedSearch = normalizeTags(searchTags);
+    return entities.filter(entity => {
+        if (!entity.tags || entity.tags.length === 0)
+            return false;
+        const normalizedEntity = normalizeTags(entity.tags);
+        return normalizedSearch.some(tag => normalizedEntity.includes(tag));
+    });
+}
+/**
+ * Adds new tags to an existing tag array, avoiding duplicates.
+ * All tags are normalized to lowercase.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param newTags - Tags to add
+ * @returns Combined tags array with no duplicates
+ */
+export function addUniqueTags(existingTags, newTags) {
+    const existing = normalizeTags(existingTags);
+    const toAdd = normalizeTags(newTags);
+    const uniqueNew = toAdd.filter(tag => !existing.includes(tag));
+    return [...existing, ...uniqueNew];
+}
+/**
+ * Removes specified tags from an existing tag array.
+ * Comparison is case-insensitive.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param tagsToRemove - Tags to remove
+ * @returns Tags array with specified tags removed
+ */
+export function removeTags(existingTags, tagsToRemove) {
+    if (!existingTags || existingTags.length === 0)
+        return [];
+    const toRemoveNormalized = normalizeTags(tagsToRemove);
+    return existingTags.filter(tag => !toRemoveNormalized.includes(tag.toLowerCase()));
+}
+// ==================== Date Utilities ====================
+/**
+ * Check if a date falls within a specified range.
+ *
+ * @param date - ISO 8601 date string to check (may be undefined)
+ * @param start - Optional start date (inclusive)
+ * @param end - Optional end date (inclusive)
+ * @returns True if date is within range or no filters are set
+ *
+ * @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
+ * isWithinDateRange(undefined); // true (no filters)
+ * isWithinDateRange(undefined, '2024-01-01T00:00:00Z'); // false (has filter but no date)
+ * ```
+ */
+export function isWithinDateRange(date, start, end) {
+    // If no filters set, always pass
+    if (!start && !end) {
+        return true;
+    }
+    // If date is undefined but we have filters, fail
+    if (!date) {
+        return false;
+    }
+    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();
+}
+// ==================== Filter Utilities ====================
+/**
+ * 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));
+}
+/**
+ * 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 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;
+}
+// ==================== Path Utilities ====================
+/**
+ * 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 project root directory, outside dist/).
+ */
+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/errors.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 declare class KnowledgeGraphError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/**
+ * Error thrown when an entity is not found.
+ */
+export declare class EntityNotFoundError extends KnowledgeGraphError {
+    constructor(entityName: string);
+}
+/**
+ * Error thrown when a relation is not found.
+ */
+export declare class RelationNotFoundError extends KnowledgeGraphError {
+    constructor(from: string, to: string, relationType?: string);
+}
+/**
+ * Error thrown when attempting to create a duplicate entity.
+ */
+export declare class DuplicateEntityError extends KnowledgeGraphError {
+    constructor(entityName: string);
+}
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends KnowledgeGraphError {
+    readonly errors: string[];
+    constructor(message: string, errors: string[]);
+}
+/**
+ * Error thrown when a cycle is detected in hierarchies.
+ */
+export declare class CycleDetectedError extends KnowledgeGraphError {
+    constructor(entityName: string, parentName: string);
+}
+/**
+ * Error thrown when an invalid importance value is provided.
+ */
+export declare class InvalidImportanceError extends KnowledgeGraphError {
+    constructor(value: number, min?: number, max?: number);
+}
+/**
+ * Error thrown when a file operation fails.
+ */
+export declare class FileOperationError extends KnowledgeGraphError {
+    constructor(operation: string, filePath: string, cause?: Error);
+}
+/**
+ * Error thrown when an import operation fails.
+ */
+export declare class ImportError extends KnowledgeGraphError {
+    constructor(format: string, message: string);
+}
+/**
+ * Error thrown when an export operation fails.
+ */
+export declare class ExportError extends KnowledgeGraphError {
+    constructor(format: string, message: string);
+}
+/**
+ * Error thrown when insufficient entities are provided for an operation.
+ */
+export declare class InsufficientEntitiesError extends KnowledgeGraphError {
+    constructor(operation: string, required: number, provided: number);
+}
+/**
+ * Phase 9B: Error thrown when an operation is cancelled via AbortSignal.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * try {
+ *   await manager.createEntities(entities, { signal: controller.signal });
+ * } catch (error) {
+ *   if (error instanceof OperationCancelledError) {
+ *     console.log('Operation was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export declare class OperationCancelledError extends KnowledgeGraphError {
+    constructor(operation?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aACC,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAQ3D;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;gBAC9C,UAAU,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;gBAChD,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAO5D;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,mBAAmB;gBAC/C,UAAU,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,mBAAmB;aAGpC,MAAM,EAAE,MAAM,EAAE;gBADhC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EAAE;CAKnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,mBAAmB;gBAC7C,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAOnD;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,mBAAmB;gBACjD,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,EAAE,GAAG,GAAE,MAAW;CAO7D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,mBAAmB;gBAEvD,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,KAAK;CAWhB;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,mBAAmB;gBACtC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,mBAAmB;gBACtC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5C;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,mBAAmB;gBACpD,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAOlE;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,SAAQ,mBAAmB;gBAClD,SAAS,CAAC,EAAE,MAAM;CAO/B"}

package/dist/utils/errors.js

@@ -119,3 +119,27 @@ export class InsufficientEntitiesError extends KnowledgeGraphError {
         this.name = 'InsufficientEntitiesError';
     }
 }
+/**
+ * Phase 9B: Error thrown when an operation is cancelled via AbortSignal.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * try {
+ *   await manager.createEntities(entities, { signal: controller.signal });
+ * } catch (error) {
+ *   if (error instanceof OperationCancelledError) {
+ *     console.log('Operation was cancelled');
+ *   }
+ * }
+ * ```
+ */
+export class OperationCancelledError extends KnowledgeGraphError {
+    constructor(operation) {
+        const message = operation
+            ? `Operation '${operation}' was cancelled`
+            : 'Operation was cancelled';
+        super(message, 'OPERATION_CANCELLED');
+        this.name = 'OperationCancelledError';
+    }
+}