@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

package/dist/utils/pathUtils.js

@@ -1,115 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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,
-    };
-}

package/dist/utils/tagUtils.js

@@ -1,107 +0,0 @@
-/**
- * Tag Normalization and Matching Utilities
- *
- * Centralizes tag operations to eliminate duplicate normalization logic
- * across the codebase. All tags are normalized to lowercase for consistent 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()));
-}

package/dist/utils/tfidf.js

@@ -1,90 +0,0 @@
-/**
- * TF-IDF (Term Frequency-Inverse Document Frequency) Utilities
- *
- * Algorithms for calculating TF-IDF scores used in ranked search.
- * TF-IDF measures how important a term is to a document in a collection.
- *
- * @module utils/tfidf
- */
-/**
- * Calculate Term Frequency (TF) for a term in a document.
- *
- * TF = (Number of times term appears in document) / (Total terms in document)
- *
- * @param term - The search term
- * @param document - The document text
- * @returns Term frequency (0.0 to 1.0)
- */
-export function calculateTF(term, document) {
-    const termLower = term.toLowerCase();
-    const tokens = tokenize(document);
-    if (tokens.length === 0)
-        return 0;
-    const termCount = tokens.filter(t => t === termLower).length;
-    return termCount / tokens.length;
-}
-/**
- * Calculate Inverse Document Frequency (IDF) for a term across documents.
- *
- * IDF = log(Total documents / Documents containing term)
- *
- * @param term - The search term
- * @param documents - Array of document texts
- * @returns Inverse document frequency
- */
-export function calculateIDF(term, documents) {
-    if (documents.length === 0)
-        return 0;
-    const termLower = term.toLowerCase();
-    const docsWithTerm = documents.filter(doc => tokenize(doc).includes(termLower)).length;
-    if (docsWithTerm === 0)
-        return 0;
-    return Math.log(documents.length / docsWithTerm);
-}
-/**
- * Calculate TF-IDF score for a term in a document.
- *
- * TF-IDF = TF * IDF
- *
- * Higher scores indicate more important/relevant terms.
- *
- * @param term - The search term
- * @param document - The document text
- * @param documents - Array of all documents
- * @returns TF-IDF score
- */
-export function calculateTFIDF(term, document, documents) {
-    const tf = calculateTF(term, document);
-    const idf = calculateIDF(term, documents);
-    return tf * idf;
-}
-/**
- * Tokenize text into lowercase words.
- *
- * Splits on whitespace and removes punctuation.
- *
- * @param text - Text to tokenize
- * @returns Array of lowercase tokens
- */
-export function tokenize(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^\w\s]/g, ' ')
-        .split(/\s+/)
-        .filter(token => token.length > 0);
-}
-/**
- * Calculate TF-IDF scores for multiple search terms.
- *
- * @param terms - Array of search terms
- * @param document - The document text
- * @param documents - Array of all documents
- * @returns Map of term to TF-IDF score
- */
-export function calculateMultiTermTFIDF(terms, document, documents) {
-    const scores = new Map();
-    for (const term of terms) {
-        scores.set(term, calculateTFIDF(term, document, documents));
-    }
-    return scores;
-}

package/dist/utils/validationHelper.js

@@ -1,99 +0,0 @@
-/**
- * Zod Schema Validation Helper
- *
- * Centralizes Zod validation patterns to eliminate redundant error formatting
- * and validation logic across the codebase.
- */
-import { ValidationError } from './errors.js';
-/**
- * Formats Zod errors into human-readable strings.
- *
- * @param error - Zod error object
- * @returns Array of formatted error messages
- */
-export function formatZodErrors(error) {
-    return error.issues.map(issue => {
-        const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
-        return `${path}${issue.message}`;
-    });
-}
-/**
- * Validates data against a Zod schema and returns the typed result.
- * Throws ValidationError with formatted error messages on failure.
- *
- * @param data - The data to validate
- * @param schema - The Zod schema to validate against
- * @param errorMessage - Custom error message prefix (default: 'Validation failed')
- * @returns The validated and typed data
- * @throws ValidationError if validation fails
- *
- * @example
- * ```typescript
- * const entities = validateWithSchema(
- *   input,
- *   BatchCreateEntitiesSchema,
- *   'Invalid entity data'
- * );
- * ```
- */
-export function validateWithSchema(data, schema, errorMessage = 'Validation failed') {
-    const result = schema.safeParse(data);
-    if (!result.success) {
-        const errors = formatZodErrors(result.error);
-        throw new ValidationError(errorMessage, errors);
-    }
-    return result.data;
-}
-/**
- * Validates data and returns a result object instead of throwing.
- * Useful when you want to handle validation errors gracefully.
- *
- * @param data - The data to validate
- * @param schema - The Zod schema to validate against
- * @returns Result object with success status and either data or errors
- *
- * @example
- * ```typescript
- * const result = validateSafe(input, EntitySchema);
- * if (result.success) {
- *   console.log(result.data);
- * } else {
- *   console.error(result.errors);
- * }
- * ```
- */
-export function validateSafe(data, schema) {
-    const result = schema.safeParse(data);
-    if (result.success) {
-        return { success: true, data: result.data };
-    }
-    return { success: false, errors: formatZodErrors(result.error) };
-}
-/**
- * Validates an array of items against a schema.
- * Returns detailed information about which items failed validation.
- *
- * @param items - Array of items to validate
- * @param schema - Zod schema for individual items
- * @param errorMessage - Custom error message prefix
- * @returns Array of validated items
- * @throws ValidationError if any item fails validation
- */
-export function validateArrayWithSchema(items, schema, errorMessage = 'Array validation failed') {
-    const errors = [];
-    const validated = [];
-    for (let i = 0; i < items.length; i++) {
-        const result = schema.safeParse(items[i]);
-        if (result.success) {
-            validated.push(result.data);
-        }
-        else {
-            const itemErrors = formatZodErrors(result.error);
-            errors.push(...itemErrors.map(e => `[${i}] ${e}`));
-        }
-    }
-    if (errors.length > 0) {
-        throw new ValidationError(errorMessage, errors);
-    }
-    return validated;
-}

package/dist/utils/validationUtils.js

@@ -1,109 +0,0 @@
-/**
- * Validation Utilities
- *
- * Helper functions for validating entities, relations, and other data structures.
- *
- * @module utils/validationUtils
- */
-import { IMPORTANCE_RANGE } from './constants.js';
-/**
- * Type guard to check if value is a non-null object.
- */
-function isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * Validate an entity object.
- *
- * Checks required fields and data types.
- *
- * @param entity - Entity to validate (unknown type for runtime validation)
- * @returns Validation result
- */
-export function validateEntity(entity) {
-    const errors = [];
-    if (!isObject(entity)) {
-        return { valid: false, errors: ['Entity must be an object'] };
-    }
-    if (!entity.name || typeof entity.name !== 'string' || entity.name.trim() === '') {
-        errors.push('Entity name is required and must be a non-empty string');
-    }
-    if (!entity.entityType || typeof entity.entityType !== 'string' || entity.entityType.trim() === '') {
-        errors.push('Entity type is required and must be a non-empty string');
-    }
-    if (!Array.isArray(entity.observations)) {
-        errors.push('Observations must be an array');
-    }
-    else if (!entity.observations.every((o) => typeof o === 'string')) {
-        errors.push('All observations must be strings');
-    }
-    if (entity.tags !== undefined) {
-        if (!Array.isArray(entity.tags)) {
-            errors.push('Tags must be an array');
-        }
-        else if (!entity.tags.every((t) => typeof t === 'string')) {
-            errors.push('All tags must be strings');
-        }
-    }
-    if (entity.importance !== undefined) {
-        if (typeof entity.importance !== 'number') {
-            errors.push('Importance must be a number');
-        }
-        else if (!validateImportance(entity.importance)) {
-            errors.push('Importance must be between 0 and 10');
-        }
-    }
-    return { valid: errors.length === 0, errors };
-}
-/**
- * Validate a relation object.
- *
- * Checks required fields and data types.
- *
- * @param relation - Relation to validate (unknown type for runtime validation)
- * @returns Validation result
- */
-export function validateRelation(relation) {
-    const errors = [];
-    if (!isObject(relation)) {
-        return { valid: false, errors: ['Relation must be an object'] };
-    }
-    if (!relation.from || typeof relation.from !== 'string' || relation.from.trim() === '') {
-        errors.push('Relation "from" is required and must be a non-empty string');
-    }
-    if (!relation.to || typeof relation.to !== 'string' || relation.to.trim() === '') {
-        errors.push('Relation "to" is required and must be a non-empty string');
-    }
-    if (!relation.relationType || typeof relation.relationType !== 'string' || relation.relationType.trim() === '') {
-        errors.push('Relation type is required and must be a non-empty string');
-    }
-    return { valid: errors.length === 0, errors };
-}
-/**
- * Validate importance level (must be 0-10).
- *
- * @param importance - Importance value to validate
- * @returns True if valid
- */
-export function validateImportance(importance) {
-    return typeof importance === 'number'
-        && !isNaN(importance)
-        && importance >= IMPORTANCE_RANGE.MIN
-        && importance <= IMPORTANCE_RANGE.MAX;
-}
-/**
- * Validate an array of tags.
- *
- * @param tags - Tags array to validate (unknown type for runtime validation)
- * @returns Validation result
- */
-export function validateTags(tags) {
-    const errors = [];
-    if (!Array.isArray(tags)) {
-        return { valid: false, errors: ['Tags must be an array'] };
-    }
-    if (!tags.every((t) => typeof t === 'string' && t.trim() !== '')) {
-        errors.push('All tags must be non-empty strings');
-    }
-    return { valid: errors.length === 0, errors };
-}