claude-mem 3.0.2 → 3.0.4

package/dist/constants.js

@@ -0,0 +1,522 @@
+/**
+ * Claude Memory System - Constants and Templates
+ *
+ * This file consolidates all prompts, instructions, and output templates
+ * used throughout the claude-mem system for better maintainability,
+ * DRYness, and easier auditing of LLM logic.
+ */
+// =============================================================================
+// ANALYSIS PROMPTS AND TEMPLATES
+// =============================================================================
+/**
+ * Entity naming patterns for the knowledge graph
+ */
+export const ENTITY_NAMING_PATTERNS = {
+    component: "Component_Name",
+    decision: "Decision_Name",
+    pattern: "Pattern_Name",
+    tool: "Tool_Name",
+    fix: "Fix_Name",
+    workflow: "Workflow_Name"
+};
+/**
+ * Available entity types for classification
+ */
+export const ENTITY_TYPES = {
+    component: "component", // UI components, modules, services
+    pattern: "pattern", // Architectural or design patterns
+    workflow: "workflow", // Processes, pipelines, sequences
+    integration: "integration", // APIs, external services, data sources
+    concept: "concept", // Abstract ideas, methodologies, principles
+    decision: "decision", // Design choices, trade-offs, solutions
+    tool: "tool", // Utilities, libraries, development tools
+    fix: "fix" // Bug fixes, patches, workarounds
+};
+/**
+ * Standard observation fields for entities
+ */
+export const OBSERVATION_FIELDS = [
+    "Core purpose: [what it fundamentally does]",
+    "Brief description: [one-line summary for session-start display]",
+    "Implementation: [key technical details, code patterns]",
+    "Dependencies: [what it requires or builds upon]",
+    "Usage context: [when/why it's used]",
+    "Performance characteristics: [speed, reliability, constraints]",
+    "Integration points: [how it connects to other systems]",
+    "Keywords: [searchable terms for this concept]",
+    "Decision rationale: [why this approach was chosen]",
+    "Next steps: [what needs to be done next with this component]",
+    "Files modified: [list of files changed]",
+    "Tools used: [development tools/commands used]"
+];
+/**
+ * Relationship types for creating meaningful entity connections
+ */
+export const RELATIONSHIP_TYPES = [
+    "executes_via", "orchestrates_through", "validates_using",
+    "provides_auth_to", "manages_state_for", "processes_events_from",
+    "caches_data_from", "routes_requests_to", "transforms_data_for",
+    "extends", "enhances_performance_of", "builds_upon",
+    "fixes_issue_in", "replaces", "optimizes",
+    "uses_tool_chain", "triggers_tool", "receives_result_from"
+];
+/**
+ * Creates the main analysis prompt for transcript compression
+ */
+export function createAnalysisPrompt(projectName, sessionId, hasCompressedContent, existingMemoriesText, toolUseChains) {
+    const incrementalSection = hasCompressedContent ? `
+INCREMENTAL COMPRESSION:
+Lines marked [ALREADY COMPRESSED] contain existing memory references.
+DO NOT re-compress these. Build upon existing patterns and connect new entities to them.
+
+EXISTING COMPRESSED MEMORIES:
+${existingMemoriesText}
+` : '';
+    const toolChainsSection = toolUseChains.length > 0 ? `
+TOOL USE CHAINS DETECTED:
+${toolUseChains.map(chain => `- Tool chain ${chain.id}: ${chain.tools.join(' → ')}`).join('\n')}
+Create relationships for these tool use sequences in the knowledge graph.
+` : '';
+    return `You are analyzing a Claude Code conversation transcript to create a sophisticated memory index system using the Model Context Protocol knowledge graph.
+
+Your task:
+1. Extract ALL key technical entities following MCP memory best practices
+2. Create rich, searchable entities with detailed observations using MCP tools
+3. Create specific, active-voice relationships between entities
+4. Return compressed summaries in STRICT JSONL format with memory/keyword references
+
+${incrementalSection}${toolChainsSection}
+
+ENTITY EXTRACTION GUIDELINES:
+Focus on these categories for creating a searchable index:
+- **Technical Components**: Functions, classes, services, APIs, databases, modules
+- **Architectural Patterns**: State management, authentication flows, data pipelines, design patterns
+- **Development Decisions**: Design choices, trade-offs, problem solutions, optimizations
+- **Workflows & Processes**: Build processes, deployment strategies, testing approaches
+- **Integration Points**: External APIs, third-party services, data sources
+- **Performance & Reliability**: Caching strategies, error handling, optimization techniques
+- **Bugs & Fixes**: Issues encountered, debugging approaches, solutions applied
+
+ENTITY FORMAT:
+- name: "${projectName}_EntityName" 
+  (Use clear, searchable names that describe WHAT it is, not session-specific IDs)
+  IMPORTANT: Include entity type in name for better categorization:
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.component}" for UI/modules/services
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.decision}" for architectural choices
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.pattern}" for design patterns
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.tool}" for libraries/tools
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.fix}" for bug fixes
+  * "${projectName}_${ENTITY_NAMING_PATTERNS.workflow}" for processes
+- entityType: Choose from:
+${Object.entries(ENTITY_TYPES).map(([key, value]) => `  * "${value}" - ${getEntityTypeDescription(key)}`).join('\n')}
+- observations: Rich, structured details for future recall:
+${OBSERVATION_FIELDS.map(field => `  * "${field}"`).join('\n')}
+  * "UUID: ${sessionId}"
+  * "Session: ${sessionId}"
+
+RELATIONSHIP FORMAT (Use specific, active voice):
+Be precise with relationships to create a meaningful graph:
+${RELATIONSHIP_TYPES.slice(0, 6).join(', ')}
+${RELATIONSHIP_TYPES.slice(6, 12).join(', ')}
+${RELATIONSHIP_TYPES.slice(12).join(', ')}
+
+OUTPUT FORMAT REQUIREMENTS:
+Return ONLY valid JSONL format (one JSON object per line, NOT an array) with this EXACT structure:
+
+EXAMPLE OUTPUT:
+${createExampleOutput(projectName, sessionId)}
+
+SUMMARY REQUIREMENTS:
+Each index entry must:
+- Be a valid JSON object with ALL required fields: timestamp, session_id, project, summary, nodes, keywords, message_count, uuid, archive_path
+- timestamp: Current ISO timestamp
+- session_id: Use EXACT session ID "${sessionId}" (no "session-" prefix)
+- project: "${projectName}"
+- summary: Describe WHAT was accomplished and WHY it matters (active voice, specific, actionable)
+  * Start with action verb: "Implemented", "Fixed", "Refactored", "Designed", "Optimized"
+  * Include the main component/feature affected
+  * Mention the key outcome or improvement
+- nodes: Array of 2-4 entity names created in knowledge graph (use type-prefixed names)
+- keywords: Array of 3-5 searchable terms (include tool names, patterns, technologies)
+- message_count: Total messages in conversation (use actual count)
+- uuid: "${sessionId}"
+- archive_path: "~/.claude-mem/archives/${sessionId}.jsonl.archive"
+
+MCP TOOL USAGE:
+1. FIRST: Call create_entities for each distinct concept/component/decision
+   - Create session entity: ${projectName}_Session_${sessionId}
+   - Create entities for major components/patterns/decisions
+   - Include rich observations with keywords and metadata
+2. THEN: Call create_relations to link related entities
+   - Link entities to session entity
+   - Create tool chain relationships via parent_tool_use_id
+   - Connect new entities to existing ones (if incremental)
+3. FINALLY: Return JSONL summaries referencing created entities
+
+INDEXING PRIORITIES:
+- Prioritize entities that will be valuable for future code recall
+- Focus on reusable patterns and solutions
+- Capture decision rationale and trade-offs
+- Include error patterns and their fixes
+- Document integration points and API usage
+- Note performance optimizations and their impact
+- Create entities for tool chains and workflows
+
+Project: ${projectName}
+Session ID: ${sessionId}
+
+CRITICAL REQUIREMENTS:
+- Create 3-15 entities depending on conversation complexity
+- Create 5-20 relationships showing entity connections
+- Return 3-10 JSONL index entries (one JSON object per line, NOT an array)
+- Each line must be valid JSON parseable with JSON.parse()
+- Each line must have ALL required fields (timestamp, session_id, project, summary, nodes, keywords, message_count, uuid, archive_path)
+- Use EXACT session ID without prefixes
+- Focus on creating a searchable index for future development
+- Original transcript will be archived as ${sessionId}.jsonl.archive
+${hasCompressedContent ? '- Build upon existing entities, do not duplicate them' : ''}
+
+Conversation to compress:`;
+}
+/**
+ * Helper function to get entity type descriptions
+ */
+function getEntityTypeDescription(type) {
+    const descriptions = {
+        component: "UI components, modules, services",
+        pattern: "Architectural or design patterns",
+        workflow: "Processes, pipelines, sequences",
+        integration: "APIs, external services, data sources",
+        concept: "Abstract ideas, methodologies, principles",
+        decision: "Design choices, trade-offs, solutions",
+        tool: "Utilities, libraries, development tools",
+        fix: "Bug fixes, patches, workarounds"
+    };
+    return descriptions[type];
+}
+/**
+ * Creates example output for the analysis prompt
+ */
+function createExampleOutput(projectName, sessionId) {
+    return `{"timestamp":"${new Date().toISOString()}","session_id":"${sessionId}","project":"${projectName}","summary":"Implemented Redis caching system with TTL support and connection pooling","nodes":["${projectName}_Component_RedisCache","${projectName}_Pattern_ConnectionPool"],"keywords":["redis","caching","ttl","connection_pooling"],"message_count":42,"uuid":"${sessionId}","archive_path":"~/.claude-mem/archives/${sessionId}.jsonl.archive"}
+{"timestamp":"${new Date().toISOString()}","session_id":"${sessionId}","project":"${projectName}","summary":"Built JWT authentication with refresh tokens and role-based access control","nodes":["${projectName}_Component_JWTAuth","${projectName}_Decision_RoleManager","${projectName}_Pattern_RefreshToken"],"keywords":["jwt","authentication","rbac","security","refresh_token"],"message_count":35,"uuid":"${sessionId}","archive_path":"~/.claude-mem/archives/${sessionId}.jsonl.archive"}
+{"timestamp":"${new Date().toISOString()}","session_id":"${sessionId}","project":"${projectName}","summary":"Fixed WebSocket memory leak by implementing proper connection cleanup handlers","nodes":["${projectName}_Fix_WebSocketLeak","${projectName}_Component_ConnectionCleanup"],"keywords":["websocket","memory_leak","cleanup","debugging"],"message_count":28,"uuid":"${sessionId}","archive_path":"~/.claude-mem/archives/${sessionId}.jsonl.archive"}`;
+}
+// =============================================================================
+// CONTEXT PRIMING TEMPLATES
+// =============================================================================
+/**
+ * System message templates for context priming
+ */
+export const CONTEXT_TEMPLATES = {
+    PRIMARY_CONTEXT: (projectName) => `Context primed for project: ${projectName}. Access memories with search_nodes("${projectName}*") or open_nodes(["entity_name"]).`,
+    RECENT_SESSIONS: (sessionList) => `Recent sessions available: ${sessionList}`,
+    AVAILABLE_ENTITIES: (type, entities, hasMore, moreCount) => `Available ${type} entities: ${entities.join(', ')}${hasMore ? ` (+${moreCount} more)` : ''}`,
+    SESSION_START_HEADER: '🧠 Active Working Context from Previous Sessions:',
+    SESSION_START_SEPARATOR: '═'.repeat(70),
+    RESUME_INSTRUCTIONS: `💡 TO RESUME: Load active components with open_nodes(["<exact_names>"])
+📊 TO EXPLORE: Search related work with search_nodes("<keywords>")`
+};
+// =============================================================================
+// SESSION START OUTPUT TEMPLATES  
+// =============================================================================
+/**
+ * Session start formatting templates
+ */
+export const SESSION_START_TEMPLATES = {
+    FOCUS_LINE: (focus) => `📌 CURRENT FOCUS: ${focus}`,
+    LAST_WORKED: (timeAgo, projectName) => `Last worked: ${timeAgo} | Project: ${projectName}`,
+    SECTIONS: {
+        COMPONENTS: '🎯 ACTIVE COMPONENTS (load these for context):',
+        DECISIONS: '🔄 RECENT DECISIONS & PATTERNS:',
+        TOOLS: '🛠️ TOOLS & INFRASTRUCTURE:',
+        FIXES: '🐛 RECENT FIXES:',
+        ACTIONS: '⚡ NEXT ACTIONS:'
+    },
+    ACTION_PREFIX: '□ ',
+    ENTITY_BULLET: '• '
+};
+/**
+ * Time formatting for "time ago" displays
+ */
+export const TIME_FORMATS = {
+    JUST_NOW: 'just now',
+    HOURS_AGO: (hours) => `${hours} hour${hours > 1 ? 's' : ''} ago`,
+    DAYS_AGO: (days) => `${days} day${days > 1 ? 's' : ''} ago`,
+    RECENTLY: 'recently'
+};
+// =============================================================================
+// HOOK RESPONSE TEMPLATES
+// =============================================================================
+/**
+ * Standard hook response structures for Claude Code integration
+ */
+export const HOOK_RESPONSES = {
+    SUCCESS: (hookEventName, message) => ({
+        hookSpecificOutput: {
+            hookEventName,
+            status: "success",
+            message
+        },
+        suppressOutput: true
+    }),
+    SKIPPED: (hookEventName, message) => ({
+        hookSpecificOutput: {
+            hookEventName,
+            status: "skipped",
+            message
+        },
+        suppressOutput: true
+    }),
+    BLOCKED: (reason) => ({
+        decision: "block",
+        reason
+    }),
+    CONTINUE: (hookEventName, additionalContext) => ({
+        continue: true,
+        ...(additionalContext && {
+            hookSpecificOutput: {
+                hookEventName,
+                additionalContext
+            }
+        })
+    }),
+    ERROR: (reason) => ({
+        decision: "block",
+        reason
+    })
+};
+/**
+ * Pre-defined hook messages
+ */
+export const HOOK_MESSAGES = {
+    COMPRESSION_SUCCESS: "Memory compression completed successfully",
+    COMPRESSION_SKIPPED: "Compression skipped - Claude SDK not available in this context",
+    COMPRESSION_FAILED: (stderr) => `Compression failed: ${stderr}`,
+    CONTEXT_LOADED: "Project context loaded successfully",
+    CONTEXT_SKIPPED: "Continuing session - context loading skipped",
+    NO_TRANSCRIPT: "No transcript path provided",
+    HOOK_ERROR: (error) => `Hook error: ${error}`
+};
+// =============================================================================
+// CONFIGURATION TEMPLATES
+// =============================================================================
+/**
+ * MCP server configuration template
+ */
+export const MCP_CONFIG_TEMPLATE = {
+    "claude-mem": {
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-memory"]
+    }
+};
+/**
+ * Hook configuration templates for Claude settings
+ */
+export const HOOK_CONFIG_TEMPLATES = {
+    PRE_COMPACT: (scriptPath) => ({
+        pattern: "*",
+        hooks: [{
+                type: "command",
+                command: scriptPath,
+                timeout: 180000
+            }]
+    }),
+    SESSION_START: (scriptPath) => ({
+        pattern: "*",
+        hooks: [{
+                type: "command",
+                command: scriptPath,
+                timeout: 30000
+            }]
+    }),
+    SESSION_END: (scriptPath) => ({
+        pattern: "*",
+        hooks: [{
+                type: "command",
+                command: scriptPath,
+                timeout: 180000
+            }]
+    })
+};
+// =============================================================================
+// CLI MESSAGES AND STATUS TEMPLATES
+// =============================================================================
+/**
+ * Command-line interface messages
+ */
+export const CLI_MESSAGES = {
+    INSTALLATION: {
+        STARTING: '🚀 Installing Claude Memory System with embedded Weaviate...',
+        SUCCESS: '🎉 Installation complete! Embedded vector database ready.',
+        HOOKS_INSTALLED: '✅ Installed hooks to ~/.claude-mem/hooks/',
+        MCP_CONFIGURED: (path) => `✅ Configured MCP memory server in ${path}`,
+        EMBEDDED_READY: '🧠 Embedded Weaviate initialized for persistent semantic memory',
+        ALREADY_INSTALLED: '⚠️  Claude Memory hooks are already installed.',
+        USE_FORCE: '   Use --force to overwrite existing installation.',
+        SETTINGS_WRITTEN: (type, path) => `✅ Installed hooks in ${type} settings\n   Settings file: ${path}`
+    },
+    NEXT_STEPS: [
+        '1. Restart Claude Code to load the new hooks',
+        '2. Use `/clear` and `/compact` in Claude Code to save and compress session memories',
+        '3. New sessions will automatically load relevant context'
+    ],
+    ERRORS: {
+        HOOKS_NOT_FOUND: '❌ Hook source files not found',
+        SETTINGS_WRITE_FAILED: (path, error) => `❌ Failed to write settings file: ${error}\n   Path: ${path}`,
+        MCP_CONFIG_PARSE_FAILED: (error) => `⚠️  Warning: Could not parse existing MCP config: ${error}`,
+        MCP_CONFIG_WRITE_FAILED: (error) => `⚠️  Warning: Could not write MCP config: ${error}`,
+        COMPRESSION_FAILED: (error) => `❌ Compression failed: ${error}`,
+        CONTEXT_LOAD_FAILED: (error) => `❌ Failed to load context: ${error}`
+    },
+    STATUS: {
+        NO_INDEX: '📚 No memory index found. Starting fresh session.',
+        NO_MATCHES: '📚 No matching memories found in index.',
+        RECENT_MEMORIES: '🧠 Recent memories from previous sessions:',
+        MEMORY_COUNT: (count) => `📚 Showing ${count} most recent memories`,
+        FULL_CONTEXT_AVAILABLE: '💡 Full context available via MCP memory tools'
+    }
+};
+// =============================================================================
+// DEBUG AND LOGGING TEMPLATES
+// =============================================================================
+/**
+ * Debug logging message templates
+ */
+export const DEBUG_MESSAGES = {
+    COMPRESSION_STARTED: '🚀 COMPRESSION STARTED',
+    TRANSCRIPT_PATH: (path) => `📁 Transcript Path: ${path}`,
+    SESSION_ID: (id) => `🔍 Session ID: ${id}`,
+    PROJECT_NAME: (name) => `📝 PROJECT NAME: ${name}`,
+    CLAUDE_SDK_CALL: '🤖 Calling Claude SDK to analyze and populate knowledge graph...',
+    TRANSCRIPT_STATS: (size, count) => `📊 Transcript size: ${size} characters, ${count} messages`,
+    COMPRESSION_COMPLETE: (count) => `✅ COMPRESSION COMPLETE\n  Total summaries extracted: ${count}`,
+    CLAUDE_PATH_FOUND: (path) => `🎯 Found Claude Code at: ${path}`,
+    MCP_CONFIG_USED: (path) => `📋 Using MCP config: ${path}`
+};
+// =============================================================================
+// SEARCH AND QUERY TEMPLATES
+// =============================================================================
+/**
+ * Knowledge graph search templates
+ */
+export const SEARCH_TEMPLATES = {
+    SEARCH_SCRIPT: (query) => `
+import { query } from "@anthropic-ai/claude-code";
+
+const searchQuery = process.env.SEARCH_QUERY || '';
+
+const result = await query({
+    prompt: "Search for: " + searchQuery,
+    options: {
+        mcpConfig: "~/.claude/.mcp.json",
+        allowedTools: ["mcp__memory__search_nodes"],
+        outputFormat: "json"
+    }
+});
+
+console.log(JSON.stringify(result));
+`,
+    SEARCH_PREFIX: "Search for: "
+};
+// =============================================================================
+// WEAVIATE INTEGRATION CONSTANTS
+// =============================================================================
+/**
+ * Weaviate MCP server configuration template
+ */
+export const WEAVIATE_MCP_CONFIG = {
+    "claude-mem": {
+        command: process.platform === 'win32'
+            ? "C:\\path\\to\\mcp-server.exe"
+            : "/usr/local/bin/mcp-server-weaviate"
+    }
+};
+/**
+ * Weaviate collection names for entities and relations
+ */
+export const WEAVIATE_COLLECTIONS = {
+    ENTITIES: 'claude_mem_entities',
+    RELATIONS: 'claude_mem_relations'
+};
+/**
+ * Default Weaviate configuration values
+ */
+export const WEAVIATE_DEFAULTS = {
+    HOST: 'localhost:8080',
+    SCHEME: 'http',
+    MCP_PATH: '/usr/local/bin/mcp-server-weaviate'
+};
+/**
+ * Weaviate-specific CLI messages
+ */
+export const WEAVIATE_MESSAGES = {
+    CONNECTION: {
+        CONNECTING: '🔗 Connecting to Weaviate server...',
+        CONNECTED: '✅ Connected to Weaviate successfully',
+        FAILED: (error) => `❌ Failed to connect to Weaviate: ${error}`,
+        DISCONNECTED: '👋 Disconnected from Weaviate'
+    },
+    MIGRATION: {
+        STARTING: '🚀 Starting migration to Weaviate backend...',
+        READING_INDEX: '📖 Reading existing memory index files...',
+        MIGRATING_ENTITIES: (count) => `🔄 Migrating ${count} entities to Weaviate...`,
+        MIGRATING_RELATIONS: (count) => `🔗 Migrating ${count} relations to Weaviate...`,
+        UPDATING_SETTINGS: '⚙️  Updating settings to use Weaviate backend...',
+        COMPLETED: '✅ Migration to Weaviate completed successfully',
+        FAILED: (error) => `❌ Migration failed: ${error}`,
+        NO_DATA: '💡 No existing data found to migrate'
+    },
+    SEARCH: {
+        SEMANTIC_SEARCH: '🧠 Using semantic search with Weaviate...',
+        KEYWORD_SEARCH: '🔍 Using keyword search with Weaviate...',
+        HYBRID_SEARCH: '🔬 Using hybrid search with Weaviate...',
+        NO_RESULTS: '📚 No results found in Weaviate database',
+        RESULTS_FOUND: (count) => `📊 Found ${count} results in Weaviate`
+    },
+    SETUP: {
+        STARTING_EMBEDDED: '🚀 Starting embedded Weaviate instance...',
+        EMBEDDED_READY: '✅ Embedded Weaviate is ready and accepting connections',
+        DOWNLOADING_BINARIES: '⬇️ Downloading Weaviate binaries (first time only)...',
+        INITIALIZING_SCHEMA: '📋 Initializing knowledge graph schema...'
+    }
+};
+/**
+ * Weaviate error messages
+ */
+export const WEAVIATE_ERRORS = {
+    CONNECTION_FAILED: 'Could not establish connection to Weaviate server',
+    MCP_SERVER_NOT_FOUND: 'Weaviate MCP server binary not found at specified path',
+    INVALID_COLLECTION: (collection) => `Invalid Weaviate collection: ${collection}`,
+    QUERY_FAILED: (query, error) => `Query failed for '${query}': ${error}`,
+    ENTITY_CREATION_FAILED: (name) => `Failed to create entity '${name}' in Weaviate`,
+    RELATION_CREATION_FAILED: (from, to) => `Failed to create relation '${from}' -> '${to}' in Weaviate`,
+    MIGRATION_INCOMPLETE: 'Migration was incomplete - some data may not have been transferred',
+    EMBEDDED_START_FAILED: 'Failed to start embedded Weaviate instance - check disk space and permissions',
+    SCHEMA_MISMATCH: 'Weaviate schema does not match expected structure'
+};
+/**
+ * Export all constants for easy importing
+ */
+export const CONSTANTS = {
+    ENTITY_NAMING_PATTERNS,
+    ENTITY_TYPES,
+    OBSERVATION_FIELDS,
+    RELATIONSHIP_TYPES,
+    CONTEXT_TEMPLATES,
+    SESSION_START_TEMPLATES,
+    TIME_FORMATS,
+    HOOK_RESPONSES,
+    HOOK_MESSAGES,
+    MCP_CONFIG_TEMPLATE,
+    HOOK_CONFIG_TEMPLATES,
+    CLI_MESSAGES,
+    DEBUG_MESSAGES,
+    SEARCH_TEMPLATES,
+    // Weaviate constants
+    WEAVIATE_MCP_CONFIG,
+    WEAVIATE_COLLECTIONS,
+    WEAVIATE_DEFAULTS,
+    WEAVIATE_MESSAGES,
+    WEAVIATE_ERRORS
+};

package/dist/error-handler.d.ts

@@ -0,0 +1,17 @@
+export declare class ErrorHandler {
+    private logger;
+    private logDir;
+    constructor(enableDebug?: boolean);
+    private ensureLogDirectory;
+    handleHookError(error: Error, hookType: string, payload?: unknown): never;
+    handleCompressionError(error: Error, transcriptPath: string, stage: string): never;
+    handleValidationError(message: string, context?: Record<string, unknown>): never;
+    logSuccess(operation: string, details?: Record<string, unknown>): void;
+    logWarning(message: string, details?: Record<string, unknown>): void;
+    logDebug(message: string, details?: Record<string, unknown>): void;
+}
+export declare function parseStdinJson<T = unknown>(input: string): T;
+export declare function safeExecute<T>(operation: () => Promise<T>, errorHandler: ErrorHandler, context: string): Promise<T>;
+export declare function validateFileExists(filePath: string, errorHandler: ErrorHandler): void;
+export declare function createHookResponse(success: boolean, data?: Record<string, unknown>): string;
+export declare const globalErrorHandler: ErrorHandler;

package/dist/error-handler.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { HookError, CompressionError, FileLogger } from './types.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export class ErrorHandler {
+    logger;
+    logDir;
+    constructor(enableDebug = false) {
+        this.logDir = join(__dirname, '..', 'logs');
+        this.ensureLogDirectory();
+        const logFile = join(this.logDir, `claude-mem-${new Date().toISOString().slice(0, 10)}.log`);
+        this.logger = new FileLogger(logFile, enableDebug);
+    }
+    ensureLogDirectory() {
+        if (!existsSync(this.logDir)) {
+            mkdirSync(this.logDir, { recursive: true });
+        }
+    }
+    handleHookError(error, hookType, payload) {
+        const hookError = error instanceof HookError
+            ? error
+            : new HookError(error.message, hookType, payload, 'HOOK_EXECUTION_ERROR');
+        this.logger.error(`Hook execution failed in ${hookType}`, hookError, {
+            hookType,
+            payload: payload ? JSON.stringify(payload) : undefined,
+        });
+        console.log(JSON.stringify({
+            continue: false,
+            stopReason: `Hook error: ${hookError.message}`,
+            error: {
+                type: hookError.name,
+                message: hookError.message,
+                code: hookError.code,
+            },
+        }));
+        process.exit(1);
+    }
+    handleCompressionError(error, transcriptPath, stage) {
+        const compressionError = error instanceof CompressionError
+            ? error
+            : new CompressionError(error.message, transcriptPath, stage);
+        this.logger.error(`Compression failed during ${stage}`, compressionError, {
+            transcriptPath,
+            stage,
+        });
+        console.error(`Compression error: ${compressionError.message}`);
+        console.error(`Stage: ${stage}`);
+        console.error(`Transcript: ${transcriptPath}`);
+        process.exit(1);
+    }
+    handleValidationError(message, context) {
+        this.logger.error('Validation error', undefined, { message, context });
+        console.error(`Validation error: ${message}`);
+        if (context) {
+            console.error('Context:', JSON.stringify(context, null, 2));
+        }
+        process.exit(1);
+    }
+    logSuccess(operation, details) {
+        this.logger.info(`Operation successful: ${operation}`, details);
+    }
+    logWarning(message, details) {
+        this.logger.warn(message, details);
+    }
+    logDebug(message, details) {
+        this.logger.debug(message, details);
+    }
+}
+export function parseStdinJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON input: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+export async function safeExecute(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const message = `Safe execution failed in ${context}: ${error instanceof Error ? error.message : String(error)}`;
+        errorHandler.handleValidationError(message, { context, error });
+        throw error;
+    }
+}
+export function validateFileExists(filePath, errorHandler) {
+    if (!existsSync(filePath)) {
+        errorHandler.handleValidationError(`File not found: ${filePath}`, {
+            filePath,
+        });
+    }
+}
+export function createHookResponse(success, data) {
+    const response = {
+        continue: success,
+        ...data,
+    };
+    return JSON.stringify(response);
+}
+export const globalErrorHandler = new ErrorHandler(process.env.DEBUG === 'true');

package/dist/mcp-server-cli.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ *
+ * OFFICIAL DOCS: @modelcontextprotocol/sdk v1.0.0
+ * Last Verified: 2025-09-01
+ *
+ * Claude-mem MCP Server CLI Entry Point
+ *
+ * This module provides the standalone entry point for running the claude-mem MCP server
+ * that communicates with Claude Code via stdio transport.
+ *
+ * Usage:
+ *   node dist/mcp-server-cli.js
+ *   claude-mem-server
+ *
+ * Communication:
+ * - Stdin/Stdout: MCP protocol messages with Claude Code
+ * - Stderr: Logging and diagnostic output
+ *
+ * Architecture:
+ * This CLI connects the MCP server to Claude Code via stdio transport,
+ * enabling Claude Code to access the embedded Weaviate knowledge graph
+ * through standard MCP memory tools.
+ *
+ * Implementation follows official MCP SDK patterns:
+ * - StdioServerTransport for stdin/stdout communication (SDK README.md#_snippet_16)
+ * - Server initialization before transport connection
+ * - Graceful shutdown handlers for SIGINT/SIGTERM
+ * - Error handling for uncaught exceptions
+ *
+ * @see docs/mcp-sdk/stdio-transport.md for transport patterns
+ */
+export {};