@danielsimonjr/memory-mcp 0.7.2 → 0.41.0

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/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/validationUtils.js

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

package/package.json

@@ -1,48 +1,50 @@
-{
-  "name": "@danielsimonjr/memory-mcp",
-  "version": "0.7.2",
-  "description": "Enhanced MCP memory server with timestamps, tags, importance, search, and export (JSON/CSV/GraphML)",
-  "license": "MIT",
-  "author": "Daniel Simon Jr. (https://github.com/danielsimonjr)",
-  "homepage": "https://github.com/danielsimonjr/memory-mcp",
-  "bugs": "https://github.com/danielsimonjr/memory-mcp/issues",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/danielsimonjr/memory-mcp.git"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "memory",
-    "knowledge-graph",
-    "enhanced",
-    "timestamps",
-    "tags",
-    "export",
-    "graphml",
-    "analytics"
-  ],
-  "type": "module",
-  "bin": {
-    "mcp-server-memory": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc && shx chmod +x dist/*.js",
-    "prepare": "npm run build",
-    "watch": "tsc --watch",
-    "test": "vitest run --coverage"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.21.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "@vitest/coverage-v8": "^2.1.8",
-    "shx": "^0.3.4",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.8"
-  }
-}
+{
+  "name": "@danielsimonjr/memory-mcp",
+  "version": "0.41.0",
+  "description": "Enhanced MCP memory server with hierarchies, compression, archiving, and 45 advanced tools",
+  "license": "MIT",
+  "author": "Daniel Simon Jr. (https://github.com/danielsimonjr)",
+  "homepage": "https://github.com/danielsimonjr/memory-mcp",
+  "bugs": "https://github.com/danielsimonjr/memory-mcp/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielsimonjr/memory-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "knowledge-graph",
+    "enhanced",
+    "timestamps",
+    "tags",
+    "export",
+    "graphml",
+    "analytics"
+  ],
+  "type": "module",
+  "bin": {
+    "mcp-server-memory": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit --noUnusedLocals --noUnusedParameters --strict"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.1",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.0.13",
+    "shx": "^0.4.0",
+    "typescript": "^5.6.2",
+    "vitest": "^4.0.13"
+  }
+}