@danielsimonjr/memory-mcp 0.48.0 → 9.8.0

package/dist/utils/schemas.js

@@ -1,18 +1,21 @@
 /**
- * Validation Schemas
+ * Validation Schemas and Helpers
  *
- * Zod schemas for input validation across the memory system.
+ * Consolidated module for Zod schemas and validation utilities.
  * Provides runtime type safety and data validation.
  *
  * @module utils/schemas
  */
 import { z } from 'zod';
 import { IMPORTANCE_RANGE } from './constants.js';
+import { ValidationError } from './errors.js';
+// ==================== Constants ====================
 /**
  * Importance range constants (imported from centralized constants).
  */
 const MIN_IMPORTANCE = IMPORTANCE_RANGE.MIN;
 const MAX_IMPORTANCE = IMPORTANCE_RANGE.MAX;
+// ==================== Base Schema Components ====================
 /**
  * ISO 8601 date string validation.
  * Accepts standard ISO format: YYYY-MM-DDTHH:mm:ss.sssZ
@@ -66,6 +69,7 @@ const relationTypeSchema = z.string()
     .min(1, 'Relation type cannot be empty')
     .max(100, 'Relation type cannot exceed 100 characters')
     .trim();
+// ==================== Entity Schemas ====================
 /**
  * Complete Entity schema with all fields.
  * Used for validating full entity objects including timestamps.
@@ -107,6 +111,7 @@ export const UpdateEntitySchema = z.object({
     importance: importanceSchema.optional(),
     parentId: entityNameSchema.optional(),
 });
+// ==================== Relation Schemas ====================
 /**
  * Complete Relation schema with all fields.
  * Used for validating full relation objects including timestamps.
@@ -130,6 +135,7 @@ export const CreateRelationSchema = z.object({
     createdAt: isoDateSchema.optional(),
     lastModified: isoDateSchema.optional(),
 });
+// ==================== Search Schemas ====================
 /**
  * Search query validation.
  * Validates text search queries with reasonable length constraints.
@@ -145,6 +151,7 @@ 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 Schemas ====================
 /**
  * Tag alias validation for TagManager.
  */
@@ -152,10 +159,12 @@ export const TagAliasSchema = z.object({
     canonical: tagSchema,
     aliases: z.array(tagSchema).min(1, 'Must have at least one alias'),
 });
+// ==================== Export Schemas ====================
 /**
  * Export format validation.
  */
 export const ExportFormatSchema = z.enum(['json', 'graphml', 'csv']);
+// ==================== Batch Operation Schemas ====================
 /**
  * Batch entity creation validation.
  * Validates array of entities with maximum constraints.
@@ -182,3 +191,294 @@ export const EntityNamesSchema = z.array(entityNameSchema)
 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');
+// ==================== Observation Schemas ====================
+/**
+ * Single observation input for add operations.
+ * Empty contents array is allowed (no-op).
+ */
+export const AddObservationInputSchema = z.object({
+    entityName: entityNameSchema,
+    contents: z.array(observationSchema),
+});
+/**
+ * Batch observation addition validation.
+ * Empty array is allowed (no-op).
+ */
+export const AddObservationsInputSchema = z.array(AddObservationInputSchema)
+    .max(1000, 'Cannot add observations to more than 1000 entities in a single batch');
+/**
+ * Single observation deletion input.
+ * Empty observations array is allowed (no-op).
+ * Non-existent entities are silently skipped by the manager.
+ */
+export const DeleteObservationInputSchema = z.object({
+    entityName: entityNameSchema,
+    observations: z.array(observationSchema),
+});
+/**
+ * Batch observation deletion validation.
+ * Empty array is allowed (no-op).
+ */
+export const DeleteObservationsInputSchema = z.array(DeleteObservationInputSchema)
+    .max(1000, 'Cannot delete observations from more than 1000 entities in a single batch');
+// ==================== Archive Schema ====================
+/**
+ * Archive criteria validation.
+ * All fields are optional - the manager handles the case when no criteria provided.
+ */
+export const ArchiveCriteriaSchema = z.object({
+    olderThan: z.string().optional(),
+    importanceLessThan: z.number().min(0).max(10).optional(),
+    tags: z.array(tagSchema).optional(),
+});
+// ==================== Saved Search Schemas ====================
+/**
+ * Saved search creation input validation.
+ */
+export const SavedSearchInputSchema = z.object({
+    name: z.string().min(1, 'Search name cannot be empty').max(200, 'Search name cannot exceed 200 characters').trim(),
+    description: z.string().max(1000, 'Description cannot exceed 1000 characters').optional(),
+    query: SearchQuerySchema,
+    tags: z.array(tagSchema).optional(),
+    minImportance: importanceSchema.optional(),
+    maxImportance: importanceSchema.optional(),
+    entityType: entityTypeSchema.optional(),
+});
+/**
+ * Saved search update validation.
+ * All fields are optional for partial updates.
+ */
+export const SavedSearchUpdateSchema = z.object({
+    description: z.string().max(1000, 'Description cannot exceed 1000 characters').optional(),
+    query: SearchQuerySchema.optional(),
+    tags: z.array(tagSchema).optional(),
+    minImportance: importanceSchema.optional(),
+    maxImportance: importanceSchema.optional(),
+    entityType: entityTypeSchema.optional(),
+});
+// ==================== Import/Export Schemas ====================
+/**
+ * Import format validation.
+ */
+export const ImportFormatSchema = z.enum(['json', 'csv', 'graphml']);
+/**
+ * Export format validation (includes all output formats).
+ */
+export const ExtendedExportFormatSchema = z.enum(['json', 'csv', 'graphml', 'gexf', 'dot', 'markdown', 'mermaid']);
+/**
+ * Merge strategy validation for imports.
+ */
+export const MergeStrategySchema = z.enum(['replace', 'skip', 'merge', 'fail']);
+/**
+ * Export filter validation.
+ */
+export const ExportFilterSchema = z.object({
+    startDate: isoDateSchema.optional(),
+    endDate: isoDateSchema.optional(),
+    entityType: entityTypeSchema.optional(),
+    tags: z.array(tagSchema).optional(),
+});
+// ==================== Search Parameter Schemas ====================
+/**
+ * Tags array validation (optional, for search filters).
+ */
+export const OptionalTagsSchema = z.array(tagSchema).optional();
+/**
+ * Optional entity names array validation.
+ */
+export const OptionalEntityNamesSchema = z.array(entityNameSchema).optional();
+// ==================== Zod Validation Helpers ====================
+/**
+ * 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;
+}
+// ==================== Manual Validation Functions ====================
+/**
+ * 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/dist/utils/searchAlgorithms.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Search Algorithms
+ *
+ * Algorithms for search operations: Levenshtein distance for fuzzy matching
+ * and TF-IDF for relevance scoring.
+ *
+ * @module utils/searchAlgorithms
+ */
+/**
+ * Calculate Levenshtein distance between two strings.
+ *
+ * Returns the minimum number of single-character edits needed to change
+ * one word into another.
+ *
+ * **Algorithm**: Space-optimized dynamic programming using only two rows.
+ * Time complexity: O(m*n), Space complexity: O(min(m,n)).
+ *
+ * This optimization reduces memory usage from O(m*n) to O(min(m,n)) by
+ * observing that each row only depends on the previous row.
+ *
+ * @param str1 - First string to compare
+ * @param str2 - Second string to compare
+ * @returns Minimum number of edits required (0 = identical strings)
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance("kitten", "sitting"); // Returns 3
+ * levenshteinDistance("hello", "hello");    // Returns 0
+ * levenshteinDistance("abc", "");           // Returns 3
+ * ```
+ */
+export declare function levenshteinDistance(str1: string, str2: string): number;
+/**
+ * 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 declare function calculateTF(term: string, document: string): number;
+/**
+ * Calculate Inverse Document Frequency (IDF) for a term across documents.
+ *
+ * IDF = log(Total documents / Documents containing term)
+ *
+ * Note: For bulk IDF calculation, prefer calculateIDFFromTokenSets which
+ * avoids re-tokenizing documents for each term.
+ *
+ * @param term - The search term
+ * @param documents - Array of document texts
+ * @returns Inverse document frequency
+ */
+export declare function calculateIDF(term: string, documents: string[]): number;
+/**
+ * Calculate Inverse Document Frequency (IDF) from pre-tokenized documents.
+ *
+ * IDF = log(Total documents / Documents containing term)
+ *
+ * **Optimized**: Avoids re-tokenizing documents for each term. Pre-tokenize
+ * documents once and convert to Sets for O(1) lookup per document.
+ *
+ * @param term - The search term (should already be lowercase)
+ * @param tokenSets - Array of Sets, each containing unique tokens for a document
+ * @returns Inverse document frequency
+ *
+ * @example
+ * ```typescript
+ * const docs = ["hello world", "hello there"];
+ * const tokenSets = docs.map(d => new Set(tokenize(d)));
+ * calculateIDFFromTokenSets("hello", tokenSets); // Low IDF (common term)
+ * calculateIDFFromTokenSets("world", tokenSets); // Higher IDF (less common)
+ * ```
+ */
+export declare function calculateIDFFromTokenSets(term: string, tokenSets: Set<string>[]): number;
+/**
+ * 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 declare function calculateTFIDF(term: string, document: string, documents: string[]): number;
+/**
+ * Tokenize text into lowercase words.
+ *
+ * Splits on whitespace and removes punctuation.
+ *
+ * @param text - Text to tokenize
+ * @returns Array of lowercase tokens
+ */
+export declare function tokenize(text: string): string[];
+//# sourceMappingURL=searchAlgorithms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"searchAlgorithms.d.ts","sourceRoot":"","sources":["../../src/utils/searchAlgorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAmCtE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAWtE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAexF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C"}

package/dist/utils/searchAlgorithms.js

@@ -0,0 +1,167 @@
+/**
+ * Search Algorithms
+ *
+ * Algorithms for search operations: Levenshtein distance for fuzzy matching
+ * and TF-IDF for relevance scoring.
+ *
+ * @module utils/searchAlgorithms
+ */
+// ==================== Levenshtein Distance ====================
+/**
+ * Calculate Levenshtein distance between two strings.
+ *
+ * Returns the minimum number of single-character edits needed to change
+ * one word into another.
+ *
+ * **Algorithm**: Space-optimized dynamic programming using only two rows.
+ * Time complexity: O(m*n), Space complexity: O(min(m,n)).
+ *
+ * This optimization reduces memory usage from O(m*n) to O(min(m,n)) by
+ * observing that each row only depends on the previous row.
+ *
+ * @param str1 - First string to compare
+ * @param str2 - Second string to compare
+ * @returns Minimum number of edits required (0 = identical strings)
+ *
+ * @example
+ * ```typescript
+ * levenshteinDistance("kitten", "sitting"); // Returns 3
+ * levenshteinDistance("hello", "hello");    // Returns 0
+ * levenshteinDistance("abc", "");           // Returns 3
+ * ```
+ */
+export function levenshteinDistance(str1, str2) {
+    // Ensure str1 is the shorter string for optimal space usage
+    if (str1.length > str2.length) {
+        [str1, str2] = [str2, str1];
+    }
+    const m = str1.length;
+    const n = str2.length;
+    // Use two rows instead of full matrix - O(min(m,n)) space
+    let prev = Array.from({ length: m + 1 }, (_, i) => i);
+    let curr = new Array(m + 1);
+    for (let j = 1; j <= n; j++) {
+        curr[0] = j; // Distance from empty string
+        for (let i = 1; i <= m; i++) {
+            if (str1[i - 1] === str2[j - 1]) {
+                // Characters match, no edit needed
+                curr[i] = prev[i - 1];
+            }
+            else {
+                // Take minimum of three operations
+                curr[i] = 1 + Math.min(prev[i - 1], // substitution
+                prev[i], // deletion
+                curr[i - 1] // insertion
+                );
+            }
+        }
+        // Swap rows for next iteration
+        [prev, curr] = [curr, prev];
+    }
+    return prev[m];
+}
+// ==================== TF-IDF ====================
+/**
+ * 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)
+ *
+ * Note: For bulk IDF calculation, prefer calculateIDFFromTokenSets which
+ * avoids re-tokenizing documents for each 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 Inverse Document Frequency (IDF) from pre-tokenized documents.
+ *
+ * IDF = log(Total documents / Documents containing term)
+ *
+ * **Optimized**: Avoids re-tokenizing documents for each term. Pre-tokenize
+ * documents once and convert to Sets for O(1) lookup per document.
+ *
+ * @param term - The search term (should already be lowercase)
+ * @param tokenSets - Array of Sets, each containing unique tokens for a document
+ * @returns Inverse document frequency
+ *
+ * @example
+ * ```typescript
+ * const docs = ["hello world", "hello there"];
+ * const tokenSets = docs.map(d => new Set(tokenize(d)));
+ * calculateIDFFromTokenSets("hello", tokenSets); // Low IDF (common term)
+ * calculateIDFFromTokenSets("world", tokenSets); // Higher IDF (less common)
+ * ```
+ */
+export function calculateIDFFromTokenSets(term, tokenSets) {
+    if (tokenSets.length === 0)
+        return 0;
+    const termLower = term.toLowerCase();
+    let docsWithTerm = 0;
+    for (const tokenSet of tokenSets) {
+        if (tokenSet.has(termLower)) {
+            docsWithTerm++;
+        }
+    }
+    if (docsWithTerm === 0)
+        return 0;
+    return Math.log(tokenSets.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);
+}