@danielsimonjr/memory-mcp 0.7.2 → 0.47.1

package/dist/utils/schemas.js

@@ -0,0 +1,184 @@
+/**
+ * Validation Schemas
+ *
+ * Zod schemas for input validation across the memory system.
+ * Provides runtime type safety and data validation.
+ *
+ * @module utils/schemas
+ */
+import { z } from 'zod';
+import { IMPORTANCE_RANGE } from './constants.js';
+/**
+ * Importance range constants (imported from centralized constants).
+ */
+const MIN_IMPORTANCE = IMPORTANCE_RANGE.MIN;
+const MAX_IMPORTANCE = IMPORTANCE_RANGE.MAX;
+/**
+ * ISO 8601 date string validation.
+ * Accepts standard ISO format: YYYY-MM-DDTHH:mm:ss.sssZ
+ */
+const isoDateSchema = z.string().datetime({ message: 'Must be a valid ISO 8601 date string' });
+/**
+ * Entity name validation.
+ * Must be a non-empty string with reasonable length constraints.
+ */
+const entityNameSchema = z.string()
+    .min(1, 'Entity name cannot be empty')
+    .max(500, 'Entity name cannot exceed 500 characters')
+    .trim();
+/**
+ * Entity type validation.
+ * Must be a non-empty string (e.g., "person", "project", "concept").
+ */
+const entityTypeSchema = z.string()
+    .min(1, 'Entity type cannot be empty')
+    .max(100, 'Entity type cannot exceed 100 characters')
+    .trim();
+/**
+ * Observation validation.
+ * Each observation must be a non-empty string.
+ */
+const observationSchema = z.string()
+    .min(1, 'Observation cannot be empty')
+    .max(5000, 'Observation cannot exceed 5000 characters');
+/**
+ * Tag validation.
+ * Tags are normalized to lowercase and must be non-empty.
+ */
+const tagSchema = z.string()
+    .min(1, 'Tag cannot be empty')
+    .max(100, 'Tag cannot exceed 100 characters')
+    .trim()
+    .toLowerCase();
+/**
+ * Importance validation.
+ * Must be a number between MIN_IMPORTANCE and MAX_IMPORTANCE (0-10).
+ */
+const importanceSchema = z.number()
+    .int('Importance must be an integer')
+    .min(MIN_IMPORTANCE, `Importance must be at least ${MIN_IMPORTANCE}`)
+    .max(MAX_IMPORTANCE, `Importance must be at most ${MAX_IMPORTANCE}`);
+/**
+ * Relation type validation.
+ * Should be in snake_case format (e.g., "works_at", "manages").
+ */
+const relationTypeSchema = z.string()
+    .min(1, 'Relation type cannot be empty')
+    .max(100, 'Relation type cannot exceed 100 characters')
+    .trim();
+/**
+ * Complete Entity schema with all fields.
+ * Used for validating full entity objects including timestamps.
+ */
+export const EntitySchema = z.object({
+    name: entityNameSchema,
+    entityType: entityTypeSchema,
+    observations: z.array(observationSchema),
+    createdAt: isoDateSchema.optional(),
+    lastModified: isoDateSchema.optional(),
+    tags: z.array(tagSchema).optional(),
+    importance: importanceSchema.optional(),
+    parentId: entityNameSchema.optional(),
+}).strict();
+/**
+ * Entity creation input schema.
+ * Used for validating user input when creating new entities.
+ * Timestamps are optional and will be auto-generated if not provided.
+ */
+export const CreateEntitySchema = z.object({
+    name: entityNameSchema,
+    entityType: entityTypeSchema,
+    observations: z.array(observationSchema),
+    tags: z.array(tagSchema).optional(),
+    importance: importanceSchema.optional(),
+    parentId: entityNameSchema.optional(),
+    createdAt: isoDateSchema.optional(),
+    lastModified: isoDateSchema.optional(),
+});
+/**
+ * Entity update input schema.
+ * All fields are optional for partial updates.
+ * Name cannot be updated (it's the unique identifier).
+ */
+export const UpdateEntitySchema = z.object({
+    entityType: entityTypeSchema.optional(),
+    observations: z.array(observationSchema).optional(),
+    tags: z.array(tagSchema).optional(),
+    importance: importanceSchema.optional(),
+    parentId: entityNameSchema.optional(),
+});
+/**
+ * Complete Relation schema with all fields.
+ * Used for validating full relation objects including timestamps.
+ */
+export const RelationSchema = z.object({
+    from: entityNameSchema,
+    to: entityNameSchema,
+    relationType: relationTypeSchema,
+    createdAt: isoDateSchema.optional(),
+    lastModified: isoDateSchema.optional(),
+}).strict();
+/**
+ * Relation creation input schema.
+ * Used for validating user input when creating new relations.
+ * Timestamps are optional and will be auto-generated if not provided.
+ */
+export const CreateRelationSchema = z.object({
+    from: entityNameSchema,
+    to: entityNameSchema,
+    relationType: relationTypeSchema,
+    createdAt: isoDateSchema.optional(),
+    lastModified: isoDateSchema.optional(),
+});
+/**
+ * Search query validation.
+ * Validates text search queries with reasonable length constraints.
+ */
+export const SearchQuerySchema = z.string()
+    .min(1, 'Search query cannot be empty')
+    .max(1000, 'Search query cannot exceed 1000 characters')
+    .trim();
+/**
+ * Date range validation for search filters.
+ */
+export const DateRangeSchema = z.object({
+    start: isoDateSchema,
+    end: isoDateSchema,
+}).refine((data) => new Date(data.start) <= new Date(data.end), { message: 'Start date must be before or equal to end date' });
+/**
+ * Tag alias validation for TagManager.
+ */
+export const TagAliasSchema = z.object({
+    canonical: tagSchema,
+    aliases: z.array(tagSchema).min(1, 'Must have at least one alias'),
+});
+/**
+ * Export format validation.
+ */
+export const ExportFormatSchema = z.enum(['json', 'graphml', 'csv']);
+/**
+ * Batch entity creation validation.
+ * Validates array of entities with maximum constraints.
+ * Empty arrays are allowed (no-op).
+ */
+export const BatchCreateEntitiesSchema = z.array(CreateEntitySchema)
+    .max(1000, 'Cannot create more than 1000 entities in a single batch');
+/**
+ * Batch relation creation validation.
+ * Validates array of relations with maximum constraints.
+ * Empty arrays are allowed (no-op).
+ */
+export const BatchCreateRelationsSchema = z.array(CreateRelationSchema)
+    .max(1000, 'Cannot create more than 1000 relations in a single batch');
+/**
+ * Entity name array validation for batch deletion.
+ */
+export const EntityNamesSchema = z.array(entityNameSchema)
+    .min(1, 'Must specify at least one entity name')
+    .max(1000, 'Cannot delete more than 1000 entities in a single batch');
+/**
+ * Relation array validation for batch deletion.
+ */
+export const DeleteRelationsSchema = z.array(CreateRelationSchema)
+    .min(1, 'Must specify at least one relation')
+    .max(1000, 'Cannot delete more than 1000 relations in a single batch');

package/dist/utils/searchCache.js

@@ -0,0 +1,209 @@
+/**
+ * Search Result Cache
+ *
+ * Simple LRU-style cache for search results with TTL support.
+ * Improves performance for repeated queries without external dependencies.
+ *
+ * @module utils/searchCache
+ */
+/**
+ * Simple LRU cache implementation for search results.
+ *
+ * Features:
+ * - Maximum size limit (LRU eviction when full)
+ * - TTL-based expiration
+ * - Cache statistics tracking
+ * - Hash-based key generation from query parameters
+ */
+export class SearchCache {
+    maxSize;
+    ttlMs;
+    cache = new Map();
+    accessOrder = [];
+    hits = 0;
+    misses = 0;
+    constructor(maxSize = 500, ttlMs = 5 * 60 * 1000 // 5 minutes default
+    ) {
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Generate cache key from query parameters.
+     */
+    generateKey(params) {
+        // Sort keys for consistent hashing
+        const sorted = Object.keys(params)
+            .sort()
+            .map(key => `${key}:${JSON.stringify(params[key])}`)
+            .join('|');
+        return sorted;
+    }
+    /**
+     * Get value from cache.
+     *
+     * @param params - Query parameters to generate cache key
+     * @returns Cached value or undefined if not found/expired
+     */
+    get(params) {
+        const key = this.generateKey(params);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.removeFromAccessOrder(key);
+            this.misses++;
+            return undefined;
+        }
+        // Update access order (move to end = most recently used)
+        this.removeFromAccessOrder(key);
+        this.accessOrder.push(key);
+        this.hits++;
+        return entry.value;
+    }
+    /**
+     * Set value in cache.
+     *
+     * @param params - Query parameters to generate cache key
+     * @param value - Value to cache
+     */
+    set(params, value) {
+        const key = this.generateKey(params);
+        // Remove old entry if exists
+        if (this.cache.has(key)) {
+            this.removeFromAccessOrder(key);
+        }
+        // Evict least recently used if at capacity
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            const lruKey = this.accessOrder.shift();
+            if (lruKey) {
+                this.cache.delete(lruKey);
+            }
+        }
+        // Add new entry
+        this.cache.set(key, {
+            value,
+            timestamp: Date.now(),
+            expiresAt: Date.now() + this.ttlMs,
+        });
+        this.accessOrder.push(key);
+    }
+    /**
+     * Invalidate all cached entries.
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+    }
+    /**
+     * Remove specific entry from access order.
+     */
+    removeFromAccessOrder(key) {
+        const index = this.accessOrder.indexOf(key);
+        if (index > -1) {
+            this.accessOrder.splice(index, 1);
+        }
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.cache.size,
+            hitRate: total > 0 ? this.hits / total : 0,
+        };
+    }
+    /**
+     * Reset cache statistics.
+     */
+    resetStats() {
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Clean up expired entries.
+     *
+     * Should be called periodically to prevent memory buildup.
+     */
+    cleanupExpired() {
+        const now = Date.now();
+        const keysToDelete = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.cache.delete(key);
+            this.removeFromAccessOrder(key);
+        }
+    }
+    /**
+     * Get current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Check if cache has entry for params.
+     */
+    has(params) {
+        const key = this.generateKey(params);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.removeFromAccessOrder(key);
+            return false;
+        }
+        return true;
+    }
+}
+/**
+ * Global search caches for different search types.
+ */
+export const searchCaches = {
+    basic: new SearchCache(),
+    ranked: new SearchCache(),
+    boolean: new SearchCache(),
+    fuzzy: new SearchCache(),
+};
+/**
+ * Clear all search caches.
+ *
+ * Should be called when graph is modified to ensure cache consistency.
+ */
+export function clearAllSearchCaches() {
+    searchCaches.basic.clear();
+    searchCaches.ranked.clear();
+    searchCaches.boolean.clear();
+    searchCaches.fuzzy.clear();
+}
+/**
+ * Get combined statistics for all caches.
+ */
+export function getAllCacheStats() {
+    return {
+        basic: searchCaches.basic.getStats(),
+        ranked: searchCaches.ranked.getStats(),
+        boolean: searchCaches.boolean.getStats(),
+        fuzzy: searchCaches.fuzzy.getStats(),
+    };
+}
+/**
+ * Clean up expired entries in all caches.
+ */
+export function cleanupAllCaches() {
+    searchCaches.basic.cleanupExpired();
+    searchCaches.ranked.cleanupExpired();
+    searchCaches.boolean.cleanupExpired();
+    searchCaches.fuzzy.cleanupExpired();
+}

package/dist/utils/tagUtils.js

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

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

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