claude-mem 3.0.2 → 3.0.4

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Error handling utilities for claude-mem
+ *
+ * Consolidates error handling patterns and JSON parsing logic
+ * to eliminate duplicate try-catch blocks and standardize error responses.
+ */
+export interface CommandError {
+    message: string;
+    code?: string | number;
+    details?: any;
+}
+export interface HookErrorResponse {
+    continue: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    decision?: string;
+    reason?: string;
+}
+export interface MCPError {
+    type: 'connection' | 'operation' | 'parsing' | 'unknown';
+    message: string;
+    originalError?: any;
+}
+/**
+ * Standardizes error handling across CLI commands and hooks
+ */
+export declare class ErrorHandler {
+    /**
+     * Handle command-line interface errors consistently
+     */
+    static handleCommandError(error: any, context?: string): CommandError;
+    /**
+     * Handle hook errors and return proper Claude Code responses
+     */
+    static handleHookError(error: any, hookName?: string): HookErrorResponse;
+    /**
+     * Handle MCP (Model Context Protocol) specific errors
+     */
+    static handleMCPError(error: any, operation?: string): MCPError;
+    /**
+     * Create user-friendly error messages
+     */
+    static createUserError(message: string, details?: any): CommandError;
+    /**
+     * Handle errors with graceful degradation
+     */
+    static handleWithFallback<T>(operation: () => T, fallback: T, context?: string): T;
+}
+/**
+ * Safe JSON parsing utilities
+ * Replaces 8+ duplicate JSON parsing try-catch blocks across the codebase
+ */
+export declare class JSONParser {
+    /**
+     * Parse JSON file safely with fallback
+     */
+    static parseFile<T = any>(filePath: string, fallback?: T): T;
+    /**
+     * Parse JSON string safely with fallback
+     */
+    static parseString<T = any>(jsonString: string, fallback?: T): T;
+    /**
+     * Stringify with consistent formatting
+     */
+    static stringify(obj: any, pretty?: boolean): string;
+    /**
+     * Validate JSON string without parsing
+     */
+    static isValidJSON(jsonString: string): boolean;
+    /**
+     * Parse with detailed error information
+     */
+    static parseWithErrorInfo<T = any>(jsonString: string): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: string;
+        position?: number;
+    };
+    /**
+     * Parse JSONL (JSON Lines) format safely
+     */
+    static parseJSONL<T = any>(jsonlString: string): T[];
+}
+/**
+ * Safe async operation wrapper
+ */
+export declare function safeAsync<T>(operation: () => Promise<T>, fallback: T, context?: string): Promise<T>;
+/**
+ * Helper to exit cleanly after handling an error
+ */
+export declare function exitWithError(error: any, context?: string): never;

package/dist/utils/error-utils.js

@@ -0,0 +1,238 @@
+/**
+ * Error handling utilities for claude-mem
+ *
+ * Consolidates error handling patterns and JSON parsing logic
+ * to eliminate duplicate try-catch blocks and standardize error responses.
+ */
+import { readFileSync } from 'fs';
+import { log } from './logger.js';
+// =============================================================================
+// ERROR HANDLER CLASS
+// =============================================================================
+/**
+ * Standardizes error handling across CLI commands and hooks
+ */
+export class ErrorHandler {
+    /**
+     * Handle command-line interface errors consistently
+     */
+    static handleCommandError(error, context) {
+        const prefix = context ? `❌ ${context}:` : '❌ Error:';
+        let message;
+        if (error instanceof Error) {
+            message = `${prefix} ${error.message}`;
+        }
+        else if (typeof error === 'string') {
+            message = `${prefix} ${error}`;
+        }
+        else {
+            message = `${prefix} An unexpected error occurred`;
+        }
+        log.error(message, error);
+        return {
+            message,
+            details: error
+        };
+    }
+    /**
+     * Handle hook errors and return proper Claude Code responses
+     */
+    static handleHookError(error, hookName) {
+        const context = hookName ? `${hookName} hook` : 'Hook';
+        const message = error instanceof Error ? error.message : String(error);
+        log.error(`${context} error: ${message}`);
+        return {
+            continue: false,
+            stopReason: `${context} failed: ${message}`,
+            suppressOutput: true
+        };
+    }
+    /**
+     * Handle MCP (Model Context Protocol) specific errors
+     */
+    static handleMCPError(error, operation) {
+        const context = operation ? `MCP ${operation}` : 'MCP operation';
+        let errorType = 'unknown';
+        let message = 'Unknown MCP error';
+        if (error instanceof Error) {
+            message = error.message;
+            // Categorize common MCP error types
+            if (message.includes('connect') || message.includes('connection')) {
+                errorType = 'connection';
+            }
+            else if (message.includes('parse') || message.includes('JSON')) {
+                errorType = 'parsing';
+            }
+            else if (message.includes('operation') || message.includes('call')) {
+                errorType = 'operation';
+            }
+        }
+        else if (typeof error === 'string') {
+            message = error;
+        }
+        const mcpError = {
+            type: errorType,
+            message: `${context} failed: ${message}`,
+            originalError: error
+        };
+        // Log the error
+        log.warning(mcpError.message);
+        return mcpError;
+    }
+    /**
+     * Create user-friendly error messages
+     */
+    static createUserError(message, details) {
+        return {
+            message,
+            details
+        };
+    }
+    /**
+     * Handle errors with graceful degradation
+     */
+    static handleWithFallback(operation, fallback, context) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (context) {
+                log.warning(`${context}: ${error}. Using fallback.`);
+            }
+            return fallback;
+        }
+    }
+}
+// =============================================================================
+// JSON PARSER CLASS
+// =============================================================================
+/**
+ * Safe JSON parsing utilities
+ * Replaces 8+ duplicate JSON parsing try-catch blocks across the codebase
+ */
+export class JSONParser {
+    /**
+     * Parse JSON file safely with fallback
+     */
+    static parseFile(filePath, fallback = {}) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                // File doesn't exist - this is often expected
+                return fallback;
+            }
+            log.warning(`Could not parse JSON file ${filePath}: ${error}`);
+            return fallback;
+        }
+    }
+    /**
+     * Parse JSON string safely with fallback
+     */
+    static parseString(jsonString, fallback = {}) {
+        try {
+            return JSON.parse(jsonString);
+        }
+        catch (error) {
+            log.warning(`Could not parse JSON string: ${error}`);
+            return fallback;
+        }
+    }
+    /**
+     * Stringify with consistent formatting
+     */
+    static stringify(obj, pretty = true) {
+        try {
+            return pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj);
+        }
+        catch (error) {
+            throw new Error(`Failed to stringify object: ${error}`);
+        }
+    }
+    /**
+     * Validate JSON string without parsing
+     */
+    static isValidJSON(jsonString) {
+        try {
+            JSON.parse(jsonString);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Parse with detailed error information
+     */
+    static parseWithErrorInfo(jsonString) {
+        try {
+            const data = JSON.parse(jsonString);
+            return { success: true, data };
+        }
+        catch (error) {
+            let errorMessage = 'Unknown JSON parsing error';
+            let position;
+            if (error instanceof SyntaxError) {
+                errorMessage = error.message;
+                // Try to extract position from error message
+                const positionMatch = errorMessage.match(/position (\d+)/);
+                if (positionMatch) {
+                    position = parseInt(positionMatch[1]);
+                }
+            }
+            return {
+                success: false,
+                error: errorMessage,
+                position
+            };
+        }
+    }
+    /**
+     * Parse JSONL (JSON Lines) format safely
+     */
+    static parseJSONL(jsonlString) {
+        const lines = jsonlString.trim().split('\n');
+        const results = [];
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            if (!line)
+                continue; // Skip empty lines
+            try {
+                const parsed = JSON.parse(line);
+                results.push(parsed);
+            }
+            catch (error) {
+                log.warning(`Could not parse JSONL line ${i + 1}: ${error}`);
+                // Continue processing other lines
+            }
+        }
+        return results;
+    }
+}
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+/**
+ * Safe async operation wrapper
+ */
+export async function safeAsync(operation, fallback, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (context) {
+            log.warning(`${context}: ${error}. Using fallback.`);
+        }
+        return fallback;
+    }
+}
+/**
+ * Helper to exit cleanly after handling an error
+ */
+export function exitWithError(error, context) {
+    ErrorHandler.handleCommandError(error, context);
+    process.exit(1);
+}
+// Moved to constants.ts - use HOOK_RESPONSES.SUCCESS() or HOOK_RESPONSES.ERROR() instead

package/dist/utils/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utilities Index - Main exports for claude-mem utilities
+ *
+ * This module provides clean, centralized exports for all utility modules
+ * used throughout the claude-mem system.
+ */
+export { getMCPClient, createMCPClient, resetMCPClient, isMCPClientActive, getCurrentSettings, withMCPClient } from './mcp-client.js';
+export { WeaviateMCPAdapter, createWeaviateMCPAdapter } from './weaviate-mcp-adapter.js';
+export type { IMCPClient, MCPEntity, MCPRelation, MCPSearchResult, Settings } from '../types.js';
+import { getMCPClient as _getMCPClient, createMCPClient as _createMCPClient, resetMCPClient as _resetMCPClient, withMCPClient as _withMCPClient } from './mcp-client.js';
+import { createWeaviateMCPAdapter as _createWeaviateMCPAdapter } from './weaviate-mcp-adapter.js';
+declare const _default: {
+    getMCPClient: typeof _getMCPClient;
+    createMCPClient: typeof _createMCPClient;
+    resetMCPClient: typeof _resetMCPClient;
+    withMCPClient: typeof _withMCPClient;
+    createWeaviateMCPAdapter: typeof _createWeaviateMCPAdapter;
+};
+export default _default;

package/dist/utils/index.js

@@ -0,0 +1,26 @@
+/**
+ * Utilities Index - Main exports for claude-mem utilities
+ *
+ * This module provides clean, centralized exports for all utility modules
+ * used throughout the claude-mem system.
+ */
+// =============================================================================
+// MCP CLIENT MODULES
+// =============================================================================
+export { getMCPClient, createMCPClient, resetMCPClient, isMCPClientActive, getCurrentSettings, withMCPClient } from './mcp-client.js';
+export { WeaviateMCPAdapter, createWeaviateMCPAdapter } from './weaviate-mcp-adapter.js';
+// =============================================================================
+// DEFAULT EXPORT FOR CONVENIENCE
+// =============================================================================
+// Import functions again for default export (required for shorthand property syntax)
+import { getMCPClient as _getMCPClient, createMCPClient as _createMCPClient, resetMCPClient as _resetMCPClient, withMCPClient as _withMCPClient } from './mcp-client.js';
+import { createWeaviateMCPAdapter as _createWeaviateMCPAdapter } from './weaviate-mcp-adapter.js';
+export default {
+    // Main MCP client interface
+    getMCPClient: _getMCPClient,
+    createMCPClient: _createMCPClient,
+    resetMCPClient: _resetMCPClient,
+    withMCPClient: _withMCPClient,
+    // Weaviate implementation
+    createWeaviateMCPAdapter: _createWeaviateMCPAdapter
+};

package/dist/utils/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Simple logging utility for claude-mem
+ */
+export interface LogLevel {
+    DEBUG: number;
+    INFO: number;
+    WARN: number;
+    ERROR: number;
+}
+declare class Logger {
+    private level;
+    setLevel(level: keyof LogLevel): void;
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, error?: any, context?: any): void;
+}
+export declare const log: Logger;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,42 @@
+/**
+ * Simple logging utility for claude-mem
+ */
+const LOG_LEVELS = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+};
+class Logger {
+    level = LOG_LEVELS.INFO;
+    setLevel(level) {
+        this.level = LOG_LEVELS[level];
+    }
+    debug(message, ...args) {
+        if (this.level <= LOG_LEVELS.DEBUG) {
+            console.debug(`[DEBUG] ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.level <= LOG_LEVELS.INFO) {
+            console.info(`[INFO] ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.level <= LOG_LEVELS.WARN) {
+            console.warn(`[WARN] ${message}`, ...args);
+        }
+    }
+    error(message, error, context) {
+        if (this.level <= LOG_LEVELS.ERROR) {
+            console.error(`[ERROR] ${message}`);
+            if (error) {
+                console.error(error);
+            }
+            if (context) {
+                console.error('Context:', context);
+            }
+        }
+    }
+}
+export const log = new Logger();

package/dist/utils/mcp-client-factory.d.ts

@@ -0,0 +1,51 @@
+/**
+ * MCP Client Factory for claude-mem
+ *
+ * This factory provides a unified interface for creating MCP clients based on
+ * the configured backend type. It supports both the original memory backend
+ * (using JSONL files) and the new Weaviate backend for improved search capabilities.
+ *
+ * Key Features:
+ * - Backend detection from settings (default: 'memory')
+ * - Returns appropriate client implementation
+ * - Maintains singleton patterns where applicable
+ * - Provides fallback logic for robustness
+ */
+import { Settings, IMCPClient } from '../types.js';
+/**
+ * Create an MCP client based on the configured backend type
+ *
+ * @param settings - User/project settings containing backend configuration
+ * @returns IMCPClient implementation for the specified backend
+ */
+export declare function createMCPClient(settings?: Settings): IMCPClient;
+/**
+ * Detect the best available backend based on environment and configuration
+ *
+ * This function provides intelligent fallback logic:
+ * 1. If Weaviate is configured and available, prefer it
+ * 2. Otherwise, fall back to the reliable memory backend
+ *
+ * @param settings - User settings to check
+ * @returns The recommended backend type
+ */
+export declare function detectOptimalBackend(settings?: Settings): Promise<'memory' | 'weaviate'>;
+/**
+ * Validate backend configuration and provide helpful error messages
+ *
+ * @param settings - Settings to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateBackendConfig(settings: Settings): void;
+/**
+ * Create a client with automatic backend detection and validation
+ *
+ * This is the recommended way to create MCP clients as it includes:
+ * - Backend detection and fallback logic
+ * - Configuration validation
+ * - Helpful error messages
+ *
+ * @param settings - User settings
+ * @returns Configured and validated MCP client
+ */
+export declare function createOptimalMCPClient(settings?: Settings): Promise<IMCPClient>;

package/dist/utils/mcp-client-factory.js

@@ -0,0 +1,115 @@
+/**
+ * MCP Client Factory for claude-mem
+ *
+ * This factory provides a unified interface for creating MCP clients based on
+ * the configured backend type. It supports both the original memory backend
+ * (using JSONL files) and the new Weaviate backend for improved search capabilities.
+ *
+ * Key Features:
+ * - Backend detection from settings (default: 'memory')
+ * - Returns appropriate client implementation
+ * - Maintains singleton patterns where applicable
+ * - Provides fallback logic for robustness
+ */
+import { WeaviateMCPAdapter } from './weaviate-mcp-adapter.js';
+import { MemoryMCPClient } from './memory-mcp-client.js';
+/**
+ * Create an MCP client based on the configured backend type
+ *
+ * @param settings - User/project settings containing backend configuration
+ * @returns IMCPClient implementation for the specified backend
+ */
+export function createMCPClient(settings = {}) {
+    const backend = settings.backend || 'memory';
+    switch (backend) {
+        case 'weaviate':
+            // Create Weaviate adapter with custom configuration
+            return new WeaviateMCPAdapter(settings.weaviateConfig);
+        case 'memory':
+        default:
+            // Use the traditional memory backend (JSONL files)
+            return MemoryMCPClient.getInstance();
+    }
+}
+/**
+ * Detect the best available backend based on environment and configuration
+ *
+ * This function provides intelligent fallback logic:
+ * 1. If Weaviate is configured and available, prefer it
+ * 2. Otherwise, fall back to the reliable memory backend
+ *
+ * @param settings - User settings to check
+ * @returns The recommended backend type
+ */
+export async function detectOptimalBackend(settings = {}) {
+    // If explicitly set, respect the user's choice
+    if (settings.backend) {
+        return settings.backend;
+    }
+    // Check if Weaviate is configured and accessible
+    if (settings.weaviateConfig) {
+        try {
+            // In a real implementation, this would ping Weaviate to verify availability
+            // For now, we assume if it's configured, it's preferred
+            return 'weaviate';
+        }
+        catch (error) {
+            // Fall back to memory if Weaviate is not available
+            console.warn('Weaviate backend configured but not available, falling back to memory backend');
+        }
+    }
+    // Default to the reliable memory backend
+    return 'memory';
+}
+/**
+ * Validate backend configuration and provide helpful error messages
+ *
+ * @param settings - Settings to validate
+ * @throws Error if configuration is invalid
+ */
+export function validateBackendConfig(settings) {
+    if (settings.backend === 'weaviate') {
+        if (!settings.weaviateConfig) {
+            throw new Error('Weaviate backend selected but no weaviateConfig provided');
+        }
+        const config = settings.weaviateConfig;
+        if (config.host && !config.host.includes(':')) {
+            throw new Error('Weaviate host must include port (e.g., "localhost:8080")');
+        }
+        if (config.scheme && !['http', 'https'].includes(config.scheme)) {
+            throw new Error('Weaviate scheme must be "http" or "https"');
+        }
+    }
+}
+/**
+ * Create a client with automatic backend detection and validation
+ *
+ * This is the recommended way to create MCP clients as it includes:
+ * - Backend detection and fallback logic
+ * - Configuration validation
+ * - Helpful error messages
+ *
+ * @param settings - User settings
+ * @returns Configured and validated MCP client
+ */
+export async function createOptimalMCPClient(settings = {}) {
+    try {
+        // Validate configuration first
+        validateBackendConfig(settings);
+        // Detect optimal backend
+        const optimalBackend = await detectOptimalBackend(settings);
+        // Create client with detected backend
+        const clientSettings = {
+            ...settings,
+            backend: optimalBackend
+        };
+        return createMCPClient(clientSettings);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        console.warn(`Failed to create optimal MCP client: ${errorMessage}`);
+        console.warn('Falling back to memory backend');
+        // Last resort: always fall back to memory backend
+        return MemoryMCPClient.getInstance();
+    }
+}

package/dist/utils/mcp-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * MCP Client for claude-mem
+ *
+ * This module provides the main interface for MCP operations in claude-mem.
+ * It uses embedded Weaviate as the only backend for persistent storage.
+ *
+ * Key Features:
+ * - Embedded Weaviate instance (no external dependencies)
+ * - Singleton pattern for efficient resource usage
+ * - Persistent storage across sessions
+ * - Clean interface matching existing usage patterns
+ */
+import { IMCPClient, Settings } from '../types.js';
+/**
+ * Get or create an MCP client instance
+ *
+ * This function maintains a singleton pattern using embedded Weaviate.
+ * The client persists across calls for efficient resource usage.
+ *
+ * @param settings - Configuration settings for the client (optional)
+ * @returns IMCPClient instance
+ */
+export declare function getMCPClient(settings?: Settings): Promise<IMCPClient>;
+/**
+ * Create a new MCP client (bypasses singleton)
+ *
+ * Use this when you need a fresh client instance without affecting
+ * the global singleton. Useful for testing or parallel operations.
+ *
+ * @param settings - Configuration settings for the client (optional)
+ * @returns New IMCPClient instance
+ */
+export declare function createMCPClient(settings?: Settings): Promise<IMCPClient>;
+/**
+ * Disconnect and reset the global MCP client
+ *
+ * This function properly cleans up the singleton instance and
+ * allows for a fresh client to be created on the next call.
+ */
+export declare function resetMCPClient(): Promise<void>;
+/**
+ * Check if MCP client is connected
+ *
+ * @returns True if a client instance exists (may not be connected yet)
+ */
+export declare function isMCPClientActive(): boolean;
+/**
+ * Get current client settings (read-only)
+ *
+ * @returns Copy of current settings or null if no client exists
+ */
+export declare function getCurrentSettings(): Settings | null;
+/**
+ * Perform an MCP operation with automatic client management
+ *
+ * This helper function automatically handles client creation, connection,
+ * and error handling for common MCP operations.
+ *
+ * @param operation - Function that performs the MCP operation
+ * @param settings - Settings for the MCP client
+ * @returns Result of the operation
+ */
+export declare function withMCPClient<T>(operation: (client: IMCPClient) => Promise<T>, settings?: Settings): Promise<T>;
+/**
+ * Default export maintains backward compatibility
+ */
+declare const _default: {
+    getMCPClient: typeof getMCPClient;
+    createMCPClient: typeof createMCPClient;
+    resetMCPClient: typeof resetMCPClient;
+    isMCPClientActive: typeof isMCPClientActive;
+    getCurrentSettings: typeof getCurrentSettings;
+    withMCPClient: typeof withMCPClient;
+};
+export default _default;