@danielsimonjr/memory-mcp 12.2.3 → 12.5.2

package/dist/utils/entityUtils.js

@@ -1,538 +0,0 @@
-/**
- * Entity Utilities
- *
- * 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 { 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) {
-        throw new EntityNotFoundError(name);
-    }
-    return entity ?? null;
-}
-/**
- * Finds multiple entities by name.
- *
- * @param graph - The knowledge graph to search
- * @param names - Array of entity names to find
- * @param throwIfAnyNotFound - Whether to throw if any entity doesn't exist (default: true)
- * @returns Array of found entities (may be shorter than names if throwIfAnyNotFound is false)
- * @throws EntityNotFoundError if any entity not found and throwIfAnyNotFound is true
- */
-export function findEntitiesByNames(graph, names, throwIfAnyNotFound = true) {
-    const entities = [];
-    for (const name of names) {
-        const entity = findEntityByName(graph, name, false);
-        if (entity) {
-            entities.push(entity);
-        }
-        else if (throwIfAnyNotFound) {
-            throw new EntityNotFoundError(name);
-        }
-    }
-    return entities;
-}
-/**
- * Checks if an entity exists in the graph.
- *
- * @param graph - The knowledge graph to search
- * @param name - The entity name to check
- * @returns true if entity exists, false otherwise
- */
-export function entityExists(graph, name) {
-    return graph.entities.some(e => e.name === name);
-}
-/**
- * Gets the index of an entity in the graph's entities array.
- *
- * @param graph - The knowledge graph to search
- * @param name - The entity name to find
- * @returns The index if found, -1 otherwise
- */
-export function getEntityIndex(graph, name) {
-    return graph.entities.findIndex(e => e.name === name);
-}
-/**
- * Removes an entity from the graph by name.
- * Mutates the graph's entities array in place.
- *
- * @param graph - The knowledge graph to modify
- * @param name - The entity name to remove
- * @returns true if entity was removed, false if not found
- */
-export function removeEntityByName(graph, name) {
-    const index = getEntityIndex(graph, name);
-    if (index === -1)
-        return false;
-    graph.entities.splice(index, 1);
-    return true;
-}
-/**
- * Gets all entity names as a Set for fast lookup.
- *
- * @param graph - The knowledge graph
- * @returns Set of all entity names
- */
-export function getEntityNameSet(graph) {
-    return new Set(graph.entities.map(e => e.name));
-}
-/**
- * Groups entities by their type.
- *
- * @param entities - Array of entities to group
- * @returns Map of entity type to array of entities
- */
-export function groupEntitiesByType(entities) {
-    const groups = new Map();
-    for (const entity of entities) {
-        const type = entity.entityType;
-        if (!groups.has(type)) {
-            groups.set(type, []);
-        }
-        groups.get(type).push(entity);
-    }
-    return groups;
-}
-/**
- * Updates the lastModified timestamp on an entity.
- * Mutates the entity in place.
- *
- * @param entity - The entity to update
- * @returns The updated entity (same reference)
- */
-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 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/errors.d.ts

@@ -1,77 +0,0 @@
-/**
- * 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);
-}
-//# sourceMappingURL=errors.d.ts.map

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

@@ -1 +0,0 @@
-{"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"}