claude-mem 3.0.2 → 3.0.4

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "claude-mem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ]
+    }
+  }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { PACKAGE_NAME, PACKAGE_VERSION, PACKAGE_DESCRIPTION } from './config.js';
+// Import command handlers
+import { compress } from './commands/compress.js';
+import { install } from './commands/install.js';
+import { uninstall } from './commands/uninstall.js';
+import { status } from './commands/status.js';
+import { logs } from './commands/logs.js';
+import { loadContext } from './commands/load-context.js';
+const program = new Command();
+program
+    .name(PACKAGE_NAME)
+    .description(PACKAGE_DESCRIPTION)
+    .version(PACKAGE_VERSION);
+// Compress command
+program
+    .command('compress [transcript]')
+    .description('Compress a Claude Code transcript into memory')
+    .option('--output <path>', 'Output directory for compressed files')
+    .option('--dry-run', 'Show what would be compressed without doing it')
+    .option('-v, --verbose', 'Show detailed output')
+    .action(compress);
+// Install command
+program
+    .command('install')
+    .description('Install Claude Code hooks for automatic compression')
+    .option('--global', 'Install globally (default)')
+    .option('--project', 'Install for current project only')
+    .option('--force', 'Force installation even if already installed')
+    .action(install);
+// Uninstall command
+program
+    .command('uninstall')
+    .description('Remove Claude Code hooks')
+    .option('--global', 'Remove from global settings')
+    .option('--project', 'Remove from project settings')
+    .option('--all', 'Remove from both global and project settings')
+    .action(uninstall);
+// Status command
+program
+    .command('status')
+    .description('Check installation status of Claude Memory System')
+    .action(status);
+// Logs command
+program
+    .command('logs')
+    .description('View claude-mem operation logs')
+    .option('--debug', 'Show debug logs only')
+    .option('--error', 'Show error logs only')
+    .option('--tail [n]', 'Show last n lines', '50')
+    .option('--follow', 'Follow log output')
+    .action(logs);
+// Load-context command
+program
+    .command('load-context')
+    .description('Load compressed memories for current session')
+    .option('--project <name>', 'Filter by project name')
+    .option('--count <n>', 'Number of memories to load', '10')
+    .option('--raw', 'Output raw JSON instead of formatted text')
+    .option('--format <type>', 'Output format: json, session-start, or default')
+    .action(loadContext);
+// Parse arguments and execute
+program.parse();

package/dist/commands/compress.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export declare function compress(transcript?: string, options?: OptionValues): Promise<void>;

package/dist/commands/compress.js

@@ -0,0 +1,59 @@
+import { existsSync } from 'fs';
+import { dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export async function compress(transcript, options = {}) {
+    if (!transcript) {
+        console.error('❌ Transcript file path is required');
+        process.exit(1);
+    }
+    if (!existsSync(transcript)) {
+        console.error(`❌ Transcript file not found: ${transcript}`);
+        process.exit(1);
+    }
+    console.log(`🗜️  Compressing transcript: ${transcript}`);
+    if (options.dryRun) {
+        console.log('📋 Dry run mode - no files will be written');
+        return;
+    }
+    try {
+        // Import TranscriptCompressor dynamically to ensure it's available
+        const { TranscriptCompressor } = await import('../utils/TranscriptCompressor.js');
+        // Create compressor instance with debug mode based on verbose option
+        const compressor = new TranscriptCompressor({
+            debug: options.verbose || false
+        });
+        // Extract session ID from transcript filename if not provided
+        const sessionId = options.sessionId || basename(transcript, '.jsonl');
+        if (options.verbose) {
+            console.log(`📊 Starting compression with session ID: ${sessionId}`);
+        }
+        // Perform compression
+        const archivePath = await compressor.compress(transcript, sessionId);
+        console.log('✅ Compression completed successfully');
+        console.log(`📦 Archive created: ${archivePath}`);
+        if (options.output && options.output !== dirname(archivePath)) {
+            console.log(`📂 Output directory: ${options.output} (archive location may differ)`);
+        }
+    }
+    catch (error) {
+        const err = error;
+        console.error('❌ Compression failed:', err.message);
+        if (options.verbose) {
+            console.error('Stack trace:', err.stack);
+        }
+        // Provide helpful error messages for common issues
+        if (err.message.includes('Claude Code executable not found')) {
+            console.error('💡 Hint: Make sure Claude Code is installed and accessible in your PATH');
+            console.error('   Or set CLAUDE_CODE_PATH environment variable');
+        }
+        else if (err.message.includes('JWT_SECRET')) {
+            console.error('💡 Hint: Make sure JWT_SECRET is set in your MCP configuration');
+        }
+        else if (err.message.includes('No summaries extracted')) {
+            console.error('💡 Hint: The transcript may be too short or not contain analyzable content');
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export declare function install(options?: OptionValues): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,372 @@
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, copyFileSync, statSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { PACKAGE_NAME, MCP_SERVER_SCRIPT } from '../config.js';
+import { CLI_MESSAGES } from '../constants.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function ensureDirectoryStructure() {
+    const claudeMemDir = join(homedir(), '.claude-mem');
+    const hooksDir = join(claudeMemDir, 'hooks');
+    const indexDir = join(claudeMemDir, 'index');
+    const archivesDir = join(claudeMemDir, 'archives');
+    const logsDir = join(claudeMemDir, 'logs');
+    [claudeMemDir, hooksDir, indexDir, archivesDir, logsDir].forEach(dir => {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    });
+}
+function writeHookFiles() {
+    const hooksDir = join(homedir(), '.claude-mem', 'hooks');
+    const preCompactDest = join(hooksDir, 'pre-compact.js');
+    const sessionStartDest = join(hooksDir, 'session-start.js');
+    const sessionEndDest = join(hooksDir, 'session-end.js');
+    const mcpServerDest = join(homedir(), '.claude-mem', MCP_SERVER_SCRIPT);
+    // Find hooks directory relative to the package location
+    const possibleHooksPaths = [
+        resolve(join(__dirname, '..', '..', 'hooks')), // Development mode
+        resolve(join(dirname(process.execPath), 'hooks')), // Standalone executable with hooks alongside
+        resolve(join(dirname(process.execPath), '..', 'lib', 'node_modules', 'claude-mem', 'hooks')), // npm global install
+        resolve(join(dirname(process.execPath), '..', '..', 'lib', 'node_modules', 'claude-mem', 'hooks')), // npm global install (alternative path)
+    ];
+    // Find MCP server script in dist directory
+    const possibleMcpServerPaths = [
+        resolve(join(__dirname, '..', '..', 'dist', MCP_SERVER_SCRIPT)), // Development mode - look in project dist/
+        resolve(join(__dirname, '..', MCP_SERVER_SCRIPT)), // Development mode - compiled to same dist/
+        resolve(join(dirname(process.execPath), '..', 'lib', 'node_modules', 'claude-mem', 'dist', MCP_SERVER_SCRIPT)), // npm global install
+        resolve(join(dirname(process.execPath), '..', '..', 'lib', 'node_modules', 'claude-mem', 'dist', MCP_SERVER_SCRIPT)), // npm global install (alternative path)
+        resolve(join(dirname(process.execPath), MCP_SERVER_SCRIPT)), // Standalone executable with script alongside
+    ];
+    let preCompactSource = null;
+    let sessionStartSource = null;
+    let sessionEndSource = null;
+    let mcpServerSource = null;
+    for (const hooksPath of possibleHooksPaths) {
+        const preCompactCandidate = join(hooksPath, 'pre-compact.js');
+        const sessionStartCandidate = join(hooksPath, 'session-start.js');
+        const sessionEndCandidate = join(hooksPath, 'session-end.js');
+        if (existsSync(preCompactCandidate) && existsSync(sessionStartCandidate)) {
+            preCompactSource = preCompactCandidate;
+            sessionStartSource = sessionStartCandidate;
+            // Check for session-end.js, but don't require it for backward compatibility
+            if (existsSync(sessionEndCandidate)) {
+                sessionEndSource = sessionEndCandidate;
+            }
+            break;
+        }
+    }
+    // Find MCP server script
+    for (const mcpServerPath of possibleMcpServerPaths) {
+        if (existsSync(mcpServerPath)) {
+            mcpServerSource = mcpServerPath;
+            break;
+        }
+    }
+    if (preCompactSource && sessionStartSource) {
+        copyFileSync(preCompactSource, preCompactDest);
+        copyFileSync(sessionStartSource, sessionStartDest);
+        // Copy session-end.js if it exists
+        if (sessionEndSource) {
+            copyFileSync(sessionEndSource, sessionEndDest);
+            chmodSync(sessionEndDest, 0o755);
+        }
+        chmodSync(preCompactDest, 0o755);
+        chmodSync(sessionStartDest, 0o755);
+        // Copy MCP server script
+        if (mcpServerSource) {
+            copyFileSync(mcpServerSource, mcpServerDest);
+            chmodSync(mcpServerDest, 0o755);
+            console.log('✅ MCP server script installed');
+        }
+        else {
+            console.error('❌ MCP server script not found');
+            console.error('Searched in:');
+            possibleMcpServerPaths.forEach(path => console.error(`  - ${path}`));
+            process.exit(1);
+        }
+        // Write a configuration file for hooks to know the package name
+        const hookConfigPath = join(hooksDir, 'config.json');
+        const hookConfig = {
+            packageName: PACKAGE_NAME,
+            cliCommand: PACKAGE_NAME, // The command to call (claude-mem)
+            backend: 'weaviate' // Always use embedded Weaviate
+        };
+        writeFileSync(hookConfigPath, JSON.stringify(hookConfig, null, 2));
+        console.log(CLI_MESSAGES.INSTALLATION.HOOKS_INSTALLED);
+        // Validate MCP server script installation
+        if (existsSync(mcpServerDest)) {
+            try {
+                // Test script has execute permissions by checking file stats
+                const stats = statSync(mcpServerDest);
+                if (stats.mode & parseInt('100', 8)) {
+                    console.log('✅ MCP server script validated');
+                }
+                else {
+                    console.warn('⚠️  MCP server script may not be executable');
+                }
+            }
+            catch (error) {
+                console.warn(`⚠️  MCP server script validation failed: ${error.message}`);
+            }
+        }
+        else {
+            console.error('❌ MCP server script validation failed - file not found');
+            process.exit(1);
+        }
+    }
+    else {
+        console.error(CLI_MESSAGES.ERRORS.HOOKS_NOT_FOUND);
+        console.error('Searched in:');
+        possibleHooksPaths.forEach(path => console.error(`  - ${path}`));
+        process.exit(1);
+    }
+}
+/**
+ * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+ *
+ * OFFICIAL DOCS: Claude Code MCP Configuration v2025
+ * Last Verified: 2025-08-31
+ * @see https://docs.anthropic.com/en/docs/claude-code/mcp
+ *
+ * MCP Config File Locations (per official docs):
+ * - User scope: ~/.claude.json
+ * - Project scope: ./.mcp.json (checked into version control)
+ * - Local scope: Not officially documented (implementation decision)
+ *
+ * @see docs/claude-code/mcp-configuration.md
+ */
+function configureMcpServer(settingsDir, scope) {
+    // Determine the correct MCP config file based on scope
+    let mcpConfigPath;
+    if (scope === 'user') {
+        // User scope: ~/.claude.json
+        mcpConfigPath = join(homedir(), '.claude.json');
+    }
+    else if (scope === 'project') {
+        // Project scope: .mcp.json in current directory
+        mcpConfigPath = join(process.cwd(), '.mcp.json');
+    }
+    else {
+        // Local scope: use .claude.json with project-specific section
+        mcpConfigPath = join(homedir(), '.claude.json');
+    }
+    let config = {};
+    if (existsSync(mcpConfigPath)) {
+        try {
+            config = JSON.parse(readFileSync(mcpConfigPath, 'utf8'));
+        }
+        catch (error) {
+            console.log(CLI_MESSAGES.ERRORS.MCP_CONFIG_PARSE_FAILED(error.message));
+            return; // Don't overwrite a file we can't parse
+        }
+    }
+    if (!config.mcpServers) {
+        config.mcpServers = {};
+    }
+    // Only add/update the server for this package, preserve everything else
+    // Use local MCP server script with embedded Weaviate instead of npx
+    config.mcpServers[PACKAGE_NAME] = {
+        command: "node",
+        args: [join(homedir(), '.claude-mem', MCP_SERVER_SCRIPT)]
+    };
+    try {
+        writeFileSync(mcpConfigPath, JSON.stringify(config, null, 2));
+        console.log(CLI_MESSAGES.INSTALLATION.MCP_CONFIGURED(mcpConfigPath));
+        console.log('✅ Configured embedded Weaviate MCP server');
+    }
+    catch (error) {
+        console.log(CLI_MESSAGES.ERRORS.MCP_CONFIG_WRITE_FAILED(error.message));
+    }
+}
+export async function install(options = {}) {
+    console.log(CLI_MESSAGES.INSTALLATION.STARTING);
+    console.log('🧠 Installing embedded Weaviate MCP server for persistent semantic memory');
+    // Ensure claude-mem directory structure exists
+    ensureDirectoryStructure();
+    // Determine which settings file to use
+    let settingsDir;
+    let settingsFile;
+    let settingsType;
+    if (options.local) {
+        settingsDir = join(process.cwd(), '.claude');
+        settingsFile = 'settings.local.json';
+        settingsType = 'Local';
+    }
+    else if (options.project) {
+        settingsDir = join(process.cwd(), '.claude');
+        settingsFile = 'settings.json';
+        settingsType = 'Project';
+    }
+    else {
+        // Default to user settings (--user or --global or no flag)
+        settingsDir = join(homedir(), '.claude');
+        settingsFile = 'settings.json';
+        settingsType = 'User';
+    }
+    const settingsPath = join(settingsDir, settingsFile);
+    // Determine scope for MCP configuration
+    const scope = options.local ? 'local' :
+        options.project ? 'project' :
+            'user';
+    // Configure MCP server with the appropriate scope
+    configureMcpServer(settingsDir, scope);
+    // Write hook files to ~/.claude-mem/hooks/
+    writeHookFiles();
+    // Point settings to the installed hooks
+    const claudeMemHooksDir = join(homedir(), '.claude-mem', 'hooks');
+    const preCompactScript = join(claudeMemHooksDir, 'pre-compact.js');
+    const sessionStartScript = join(claudeMemHooksDir, 'session-start.js');
+    const sessionEndScript = join(claudeMemHooksDir, 'session-end.js');
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            const content = readFileSync(settingsPath, 'utf8');
+            settings = JSON.parse(content);
+        }
+        catch (error) {
+            console.log(`⚠️  Creating new settings file (could not parse existing): ${error.message}`);
+        }
+    }
+    // Ensure settings directory exists
+    if (!existsSync(settingsDir)) {
+        mkdirSync(settingsDir, { recursive: true });
+    }
+    // Initialize hooks structure if it doesn't exist
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    // Check for existing hooks from this package
+    // Non-tool hooks structure: array of { hooks: [...] } (no matcher field)
+    const hasExistingPreCompact = settings.hooks.PreCompact?.some((config) => config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('pre-compact.js')));
+    const hasExistingSessionStart = settings.hooks.SessionStart?.some((config) => config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('session-start.js')));
+    const hasExistingSessionEnd = settings.hooks.SessionEnd?.some((config) => config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('session-end.js')));
+    if ((hasExistingPreCompact || hasExistingSessionStart || hasExistingSessionEnd) && !options.force) {
+        console.log(CLI_MESSAGES.INSTALLATION.ALREADY_INSTALLED);
+        console.log(CLI_MESSAGES.INSTALLATION.USE_FORCE);
+        return;
+    }
+    // Remove existing claude-mem hooks if forcing
+    if (options.force) {
+        // Non-tool hooks: filter out configs where hooks contain our commands
+        if (settings.hooks.PreCompact) {
+            settings.hooks.PreCompact = settings.hooks.PreCompact.filter((config) => !config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('pre-compact.js')));
+            if (settings.hooks.PreCompact.length === 0) {
+                delete settings.hooks.PreCompact;
+            }
+        }
+        if (settings.hooks.SessionStart) {
+            settings.hooks.SessionStart = settings.hooks.SessionStart.filter((config) => !config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('session-start.js')));
+            if (settings.hooks.SessionStart.length === 0) {
+                delete settings.hooks.SessionStart;
+            }
+        }
+        if (settings.hooks.SessionEnd) {
+            settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter((config) => !config.hooks?.some((hook) => hook.command?.includes(PACKAGE_NAME) || hook.command?.includes('session-end.js')));
+            if (settings.hooks.SessionEnd.length === 0) {
+                delete settings.hooks.SessionEnd;
+            }
+        }
+    }
+    /**
+     * 🔒 LOCKED by @docs-agent | Change to 🔑 to allow @docs-agent edits
+     *
+     * OFFICIAL DOCS: Claude Code Hooks Configuration v2025
+     * Last Verified: 2025-08-31
+     *
+     * Hook Configuration Structure Requirements:
+     * - Tool-related hooks (PreToolUse, PostToolUse): Use 'matcher' field for tool patterns
+     * - Non-tool hooks (PreCompact, SessionStart, SessionEnd, etc.): NO matcher/pattern field
+     *
+     * Correct Non-Tool Hook Structure:
+     * {
+     *   hooks: [{
+     *     type: "command",
+     *     command: "/path/to/script.js"
+     *   }]
+     * }
+     *
+     * @see https://docs.anthropic.com/en/docs/claude-code/hooks
+     * @see docs/claude-code/hook-configuration.md for full documentation
+     */
+    // Add PreCompact hook - Non-tool hook (no matcher field)
+    if (!settings.hooks.PreCompact) {
+        settings.hooks.PreCompact = [];
+    }
+    // ✅ CORRECT: Non-tool hooks have no 'pattern' or 'matcher' field
+    settings.hooks.PreCompact.push({
+        hooks: [
+            {
+                type: "command",
+                command: preCompactScript,
+                timeout: 180000
+            }
+        ]
+    });
+    // Add SessionStart hook - Non-tool hook (no matcher field)
+    if (!settings.hooks.SessionStart) {
+        settings.hooks.SessionStart = [];
+    }
+    // ✅ CORRECT: Non-tool hooks have no 'pattern' or 'matcher' field
+    settings.hooks.SessionStart.push({
+        hooks: [
+            {
+                type: "command",
+                command: sessionStartScript
+            }
+        ]
+    });
+    // Add SessionEnd hook (only if the file exists)
+    if (existsSync(sessionEndScript)) {
+        if (!settings.hooks.SessionEnd) {
+            settings.hooks.SessionEnd = [];
+        }
+        // ✅ CORRECT: Non-tool hooks have no 'pattern' or 'matcher' field
+        settings.hooks.SessionEnd.push({
+            hooks: [{
+                    type: "command",
+                    command: sessionEndScript,
+                    timeout: 180000
+                }]
+        });
+    }
+    // Write updated settings
+    try {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        console.log(CLI_MESSAGES.INSTALLATION.SETTINGS_WRITTEN(settingsType, settingsPath));
+        console.log('');
+        console.log(CLI_MESSAGES.INSTALLATION.SUCCESS);
+        // Store backend setting in user settings
+        const userSettingsDir = join(homedir(), '.claude-mem');
+        const userSettingsPath = join(userSettingsDir, 'settings.json');
+        let userSettings = {};
+        if (existsSync(userSettingsPath)) {
+            try {
+                userSettings = JSON.parse(readFileSync(userSettingsPath, 'utf8'));
+            }
+            catch (error) {
+                console.log(`⚠️  Creating new user settings file (could not parse existing): ${error.message}`);
+            }
+        }
+        userSettings.backend = 'weaviate';
+        userSettings.installed = true;
+        // Always use embedded Weaviate - no external config needed
+        userSettings.embedded = true;
+        try {
+            writeFileSync(userSettingsPath, JSON.stringify(userSettings, null, 2));
+            console.log(`✅ Backend configuration saved: embedded Weaviate`);
+        }
+        catch (error) {
+            console.log(`⚠️  Could not save backend settings: ${error.message}`);
+        }
+        console.log('');
+        console.log('Next steps:');
+        CLI_MESSAGES.NEXT_STEPS.forEach((step) => {
+            console.log(step);
+        });
+    }
+    catch (error) {
+        console.error(CLI_MESSAGES.ERRORS.SETTINGS_WRITE_FAILED(settingsPath, error.message));
+        process.exit(1);
+    }
+}

package/dist/commands/load-context.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export declare function loadContext(options?: OptionValues): Promise<void>;