claude-mem 3.0.2 → 3.0.4

package/dist/utils/TranscriptCompressor.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Interface for message objects in transcript
+ */
+interface TranscriptMessage {
+    type: string;
+    message?: {
+        content?: string | Array<{
+            text?: string;
+            content?: string;
+        }>;
+        role?: string;
+        timestamp?: string;
+        created_at?: string;
+    };
+    content?: string | Array<{
+        text?: string;
+        content?: string;
+    }>;
+    role?: string;
+    uuid?: string;
+    session_id?: string;
+    parent_tool_use_id?: string;
+    timestamp?: string;
+    created_at?: string;
+    subtype?: string;
+    result?: string;
+    model?: string;
+    tools?: unknown[];
+    mcp_servers?: unknown[];
+    toolUseResult?: {
+        stdout?: string;
+        stderr?: string;
+        interrupted?: boolean;
+        isImage?: boolean;
+    };
+}
+/**
+ * Interface for tool use chains extracted from messages
+ */
+interface ToolUseChain {
+    id: string;
+    tools: string[];
+    messages: TranscriptMessage[];
+}
+/**
+ * Compression options for the TranscriptCompressor
+ */
+export interface CompressionOptions {
+    output?: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+    debug?: boolean;
+}
+/**
+ * TranscriptCompressor handles the analysis and compression of Claude Code conversation transcripts
+ * into a searchable knowledge graph format using the Model Context Protocol.
+ */
+export declare class TranscriptCompressor {
+    private paths;
+    private debugMode;
+    constructor(options?: CompressionOptions);
+    /**
+     * Ensures that the required directory structure exists
+     */
+    private ensureClaudeMemStructure;
+    /**
+     * Extracts tool use chains from conversation messages
+     */
+    extractToolUseChains(messages: TranscriptMessage[]): ToolUseChain[];
+    /**
+     * Main compression method that processes a transcript and creates compressed memories
+     */
+    compress(transcriptPath: string, sessionId?: string): Promise<string>;
+    /**
+     * Finds Claude Code executable in common locations
+     */
+    private findClaudeExecutable;
+    /**
+     * Finds MCP configuration file
+     */
+    private findMCPConfig;
+    /**
+     * Processes Claude response to extract summaries
+     */
+    private processClaudeResponse;
+    /**
+     * Formats conversation messages for analysis prompt
+     */
+    private formatConversationForPrompt;
+    /**
+     * Extracts content from message object
+     */
+    private extractContent;
+    /**
+     * Summarizes tool use results
+     */
+    private summarizeToolResult;
+    /**
+     * Normalizes timestamp formats
+     */
+    private normalizeTimestamp;
+    /**
+     * Creates an archive file of the original transcript
+     */
+    private createArchive;
+    /**
+     * Appends compression summaries to the index file
+     */
+    private appendToIndex;
+}
+export {};

package/dist/utils/TranscriptCompressor.js

@@ -0,0 +1,486 @@
+import { query } from '@anthropic-ai/claude-code';
+import fs from 'fs';
+import path, { join } from 'path';
+import os from 'os';
+import { PathResolver } from './PathResolver.js';
+import { createAnalysisPrompt, DEBUG_MESSAGES } from '../constants.js';
+import { log } from './logger.js';
+import { CompressionError } from '../types.js';
+/**
+ * TranscriptCompressor handles the analysis and compression of Claude Code conversation transcripts
+ * into a searchable knowledge graph format using the Model Context Protocol.
+ */
+export class TranscriptCompressor {
+    paths;
+    debugMode;
+    constructor(options = {}) {
+        this.paths = new PathResolver();
+        this.debugMode = options.debug || false;
+        this.ensureClaudeMemStructure();
+        if (this.debugMode) {
+            log.debug('🤖 TranscriptCompressor initialized');
+        }
+    }
+    /**
+     * Ensures that the required directory structure exists
+     */
+    ensureClaudeMemStructure() {
+        const configDir = this.paths.getConfigDir();
+        const indexDir = this.paths.getIndexDir();
+        const archiveDir = this.paths.getArchiveDir();
+        const logsDir = this.paths.getLogsDir();
+        PathResolver.ensureDirectories([configDir, indexDir, archiveDir, logsDir]);
+    }
+    /**
+     * Extracts tool use chains from conversation messages
+     */
+    extractToolUseChains(messages) {
+        const chains = [];
+        const toolUseMap = new Map();
+        messages.forEach((msg) => {
+            if (msg.parent_tool_use_id) {
+                const parentId = msg.parent_tool_use_id;
+                if (!toolUseMap.has(parentId)) {
+                    toolUseMap.set(parentId, {
+                        id: parentId,
+                        tools: [],
+                        messages: [],
+                    });
+                }
+                toolUseMap.get(parentId).messages.push(msg);
+                if (msg.type === 'assistant' && msg.message?.content) {
+                    const content = Array.isArray(msg.message.content)
+                        ? msg.message.content[0]?.text || ''
+                        : msg.message.content;
+                    const toolMatch = content.match(/Using (\w+) tool/i);
+                    if (toolMatch) {
+                        toolUseMap.get(parentId).tools.push(toolMatch[1]);
+                    }
+                }
+            }
+        });
+        toolUseMap.forEach((chain) => {
+            if (chain.tools.length > 0) {
+                chains.push(chain);
+            }
+        });
+        return chains;
+    }
+    /**
+     * Main compression method that processes a transcript and creates compressed memories
+     */
+    async compress(transcriptPath, sessionId) {
+        if (this.debugMode) {
+            log.debug(DEBUG_MESSAGES.COMPRESSION_STARTED);
+            log.debug(DEBUG_MESSAGES.TRANSCRIPT_PATH(transcriptPath));
+            log.debug(DEBUG_MESSAGES.SESSION_ID(sessionId || 'auto-detected'));
+        }
+        try {
+            const projectName = PathResolver.extractProjectName(transcriptPath);
+            if (this.debugMode) {
+                log.debug(DEBUG_MESSAGES.PROJECT_NAME(projectName));
+            }
+            // Read and parse transcript
+            const content = fs.readFileSync(transcriptPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(line => line.trim());
+            const messages = [];
+            let parseErrors = 0;
+            for (let i = 0; i < lines.length; i++) {
+                try {
+                    const parsed = JSON.parse(lines[i]);
+                    messages.push(parsed);
+                }
+                catch (e) {
+                    parseErrors++;
+                    if (this.debugMode) {
+                        log.debug(`Parse error on line ${i + 1}: ${e.message}`);
+                    }
+                }
+            }
+            if (this.debugMode) {
+                log.debug(DEBUG_MESSAGES.TRANSCRIPT_STATS(content.length, messages.length));
+                if (parseErrors > 0) {
+                    log.debug(`Parse errors: ${parseErrors}`);
+                }
+            }
+            // Generate final session ID
+            const finalSessionId = sessionId || path.basename(transcriptPath, '.jsonl');
+            // Format conversation for analysis
+            const conversationText = this.formatConversationForPrompt(messages);
+            const toolUseChains = this.extractToolUseChains(messages);
+            // Create analysis prompt using the utility from constants.ts
+            const prompt = createAnalysisPrompt(projectName, finalSessionId, false, // hasCompressedContent
+            '', // existingMemoriesText
+            toolUseChains);
+            if (this.debugMode) {
+                log.debug('📤 Analysis prompt created');
+                log.debug(`📊 Prompt length: ${prompt.length} characters`);
+            }
+            // Find Claude Code executable and MCP config
+            const claudePath = this.findClaudeExecutable();
+            const mcpConfigPath = this.findMCPConfig();
+            if (this.debugMode) {
+                if (claudePath) {
+                    log.debug(DEBUG_MESSAGES.CLAUDE_PATH_FOUND(claudePath));
+                }
+                if (mcpConfigPath) {
+                    log.debug(DEBUG_MESSAGES.MCP_CONFIG_USED(mcpConfigPath));
+                }
+            }
+            // Call Claude SDK for analysis
+            const fullPrompt = `${prompt}\n\nConversation to compress:\n${conversationText}`;
+            const response = await query({
+                prompt: fullPrompt,
+                options: {
+                    maxTurns: 1,
+                    allowedTools: [
+                        'mcp__claude-mem__create_entities',
+                        'mcp__claude-mem__create_relations',
+                    ],
+                },
+            });
+            // Process response and extract summaries
+            const summaries = await this.processClaudeResponse(response);
+            if (this.debugMode) {
+                log.debug(DEBUG_MESSAGES.COMPRESSION_COMPLETE(summaries.length));
+            }
+            if (summaries.length === 0) {
+                if (this.debugMode) {
+                    log.debug('⚠️ WARNING: No summaries were extracted!');
+                }
+                throw new CompressionError('No summaries extracted from Claude response', transcriptPath, 'analyzing');
+            }
+            // Create archive and update index
+            const archivePath = this.createArchive(transcriptPath, projectName, finalSessionId, content);
+            this.appendToIndex(summaries, projectName, finalSessionId, messages, archivePath);
+            if (this.debugMode) {
+                log.debug(`✅ SUCCESS`);
+                log.debug(`Archive created: ${archivePath}`);
+                log.debug(`Summaries created: ${summaries.length}`);
+            }
+            return archivePath;
+        }
+        catch (error) {
+            log.error('COMPRESSION FAILED', error, {
+                transcriptPath,
+                sessionId
+            });
+            throw error;
+        }
+    }
+    /**
+     * Finds Claude Code executable in common locations
+     */
+    findClaudeExecutable() {
+        const possiblePaths = [
+            '/opt/homebrew/bin/claude',
+            '/usr/local/bin/claude',
+            process.env.CLAUDE_CODE_PATH,
+        ].filter(Boolean);
+        for (const path of possiblePaths) {
+            if (path && fs.existsSync(path)) {
+                return path;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Finds MCP configuration file
+     */
+    findMCPConfig() {
+        const possibleConfigs = [
+            join(process.cwd(), '.mcp.json'),
+            join(os.homedir(), '.claude.json'),
+            join(os.homedir(), '.claude', '.mcp.json'),
+        ];
+        const mcpConfigPath = possibleConfigs.find(fs.existsSync);
+        return mcpConfigPath || join(os.homedir(), '.claude.json');
+    }
+    /**
+     * Processes Claude response to extract summaries
+     */
+    async processClaudeResponse(response) {
+        const summaries = [];
+        let fullContent = '';
+        if (response && typeof response === 'object' && Symbol.asyncIterator in response) {
+            // Handle streaming response
+            for await (const message of response) {
+                if (message?.content)
+                    fullContent += message.content;
+                if (message?.text)
+                    fullContent += message.text;
+                if (message?.data)
+                    fullContent += message.data;
+                if (message?.message?.content) {
+                    if (Array.isArray(message.message.content)) {
+                        message.message.content.forEach((item) => {
+                            if (item.type === 'text' && item.text) {
+                                fullContent += item.text;
+                            }
+                        });
+                    }
+                }
+                if (message?.type === 'result' && message?.result) {
+                    fullContent = message.result;
+                }
+            }
+        }
+        else if (typeof response === 'string') {
+            fullContent = response;
+        }
+        else if (Array.isArray(response)) {
+            response.forEach((item) => {
+                if (item?.session_id && item?.summary && item?.nodes && item?.keywords) {
+                    summaries.push(item);
+                }
+            });
+        }
+        else if (typeof response === 'object' && response !== null) {
+            const obj = response;
+            if (obj.session_id && obj.summary && obj.nodes && obj.keywords) {
+                summaries.push(obj);
+            }
+        }
+        // Parse JSONL content if we have it
+        if (fullContent && summaries.length === 0) {
+            const lines = fullContent.split('\n');
+            lines.forEach((line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (parsed.session_id && parsed.summary && parsed.nodes && parsed.keywords) {
+                        summaries.push(parsed);
+                    }
+                }
+                catch (e) {
+                    if (this.debugMode) {
+                        log.debug(`Failed to parse JSONL line: ${e.message}`);
+                    }
+                }
+            });
+        }
+        return summaries;
+    }
+    /**
+     * Formats conversation messages for analysis prompt
+     */
+    formatConversationForPrompt(messages) {
+        const jsonlLines = [];
+        messages.forEach((m, index) => {
+            let role = 'unknown';
+            const messageType = m.type;
+            if (m.type === 'assistant') {
+                role = 'assistant';
+            }
+            else if (m.type === 'user') {
+                role = 'user';
+            }
+            else if (m.type === 'result') {
+                role = 'system';
+            }
+            else if (m.type === 'system') {
+                role = 'system';
+            }
+            else {
+                role = m.message?.role || m.role || 'unknown';
+            }
+            const content = this.extractContent(m);
+            if (!content || content.trim() === '') {
+                if (this.debugMode) {
+                    log.debug(`Skipping message ${index + 1}: empty content`);
+                }
+                return;
+            }
+            const timestamp = this.normalizeTimestamp(m);
+            const messageObj = {
+                type: messageType,
+                role: role,
+                content: content,
+            };
+            if (m.uuid)
+                messageObj.uuid = m.uuid;
+            if (m.session_id)
+                messageObj.session_id = m.session_id;
+            if (m.parent_tool_use_id)
+                messageObj.parent_tool_use_id = m.parent_tool_use_id;
+            if (timestamp)
+                messageObj.ts = timestamp;
+            try {
+                jsonlLines.push(JSON.stringify(messageObj));
+            }
+            catch (e) {
+                const safeObj = {
+                    type: messageType,
+                    role: role,
+                    content: String(content).replace(/[\u0000-\u001F\u007F-\u009F]/g, ''),
+                    error: 'content_sanitized',
+                };
+                if (m.uuid)
+                    safeObj.uuid = m.uuid;
+                if (m.session_id)
+                    safeObj.session_id = m.session_id;
+                if (timestamp)
+                    safeObj.ts = timestamp;
+                jsonlLines.push(JSON.stringify(safeObj));
+                if (this.debugMode) {
+                    log.debug(`Message ${index + 1} sanitized due to JSON error: ${e.message}`);
+                }
+            }
+        });
+        if (this.debugMode) {
+            log.debug(`Field filtering complete: ${jsonlLines.length} messages processed`);
+        }
+        return `\`\`\`\n${jsonlLines.join('\n')}\n\`\`\`\n\n* All dates/times are in UTC`;
+    }
+    /**
+     * Extracts content from message object
+     */
+    extractContent(m) {
+        if (m.type === 'assistant' || m.type === 'user') {
+            const messageContent = m.message?.content;
+            if (messageContent) {
+                if (Array.isArray(messageContent)) {
+                    return messageContent
+                        .map((item) => {
+                        if (typeof item === 'string')
+                            return item;
+                        if (item.text)
+                            return item.text;
+                        if (item.content)
+                            return item.content;
+                        return '';
+                    })
+                        .filter(Boolean)
+                        .join(' ');
+                }
+                return String(messageContent).trim();
+            }
+        }
+        else if (m.type === 'result') {
+            if (m.subtype === 'success' && m.result) {
+                return `[Result: ${m.result}]`;
+            }
+            else if (m.subtype === 'error_max_turns') {
+                return '[Error: Maximum turns reached]';
+            }
+            else if (m.subtype === 'error_during_execution') {
+                return '[Error during execution]';
+            }
+        }
+        else if (m.type === 'system' && m.subtype === 'init') {
+            return `[System initialized: ${m.model}, tools: ${m.tools?.length || 0}, MCP servers: ${m.mcp_servers?.length || 0}]`;
+        }
+        let content = m.message?.content || m.content || '';
+        if (Array.isArray(content)) {
+            content = content
+                .map((item) => {
+                if (typeof item === 'string')
+                    return item;
+                if (typeof item === 'object' && item !== null) {
+                    const obj = item;
+                    if (obj.text)
+                        return obj.text;
+                    if (obj.content)
+                        return obj.content;
+                }
+                return '';
+            })
+                .filter(Boolean)
+                .join(' ');
+        }
+        if (m.toolUseResult) {
+            const toolSummary = this.summarizeToolResult(m.toolUseResult, String(content));
+            if (toolSummary) {
+                content = content ? `${content}\n\n${toolSummary}` : toolSummary;
+            }
+        }
+        return String(content).trim();
+    }
+    /**
+     * Summarizes tool use results
+     */
+    summarizeToolResult(toolResult, existingContent) {
+        const summaryParts = [];
+        if (toolResult.stdout) {
+            const stdout = String(toolResult.stdout);
+            if (stdout.length > 200) {
+                const lineCount = stdout.split('\n').length;
+                const charCount = stdout.length;
+                const lines = stdout.split('\n');
+                const preview = lines.slice(0, 3).join('\n');
+                const suffix = lines.length > 6 ? `\n...\n${lines.slice(-2).join('\n')}` : '';
+                summaryParts.push(`Result: ${preview}${suffix} (${lineCount} lines, ${charCount} chars)`);
+            }
+            else {
+                summaryParts.push(`Result: ${stdout}`);
+            }
+        }
+        if (toolResult.stderr && toolResult.stderr.trim()) {
+            summaryParts.push(`Error: ${toolResult.stderr.substring(0, 150)}${toolResult.stderr.length > 150 ? '...' : ''}`);
+        }
+        if (toolResult.interrupted) {
+            summaryParts.push('(interrupted)');
+        }
+        if (toolResult.isImage) {
+            summaryParts.push('(image output)');
+        }
+        return summaryParts.join('\n');
+    }
+    /**
+     * Normalizes timestamp formats
+     */
+    normalizeTimestamp(m) {
+        const ts = m.timestamp || m.message?.timestamp || m.created_at || m.message?.created_at;
+        if (!ts)
+            return '';
+        try {
+            const date = new Date(ts);
+            if (isNaN(date.getTime()))
+                return '';
+            return date.toISOString().slice(0, 19).replace('T', ' ');
+        }
+        catch (e) {
+            if (this.debugMode) {
+                log.debug(`Invalid timestamp format: ${ts}`);
+            }
+            return '';
+        }
+    }
+    /**
+     * Creates an archive file of the original transcript
+     */
+    createArchive(transcriptPath, projectName, sessionId, content) {
+        const projectArchiveDir = this.paths.getProjectArchiveDir(projectName);
+        PathResolver.ensureDirectory(projectArchiveDir);
+        const archivePath = join(projectArchiveDir, `${sessionId}.jsonl.archive`);
+        fs.writeFileSync(archivePath, content);
+        if (this.debugMode) {
+            log.debug(`📦 Created archive: ${archivePath}`);
+        }
+        return archivePath;
+    }
+    /**
+     * Appends compression summaries to the index file
+     */
+    appendToIndex(summaries, projectName, sessionId, messages, archivePath) {
+        const indexPath = this.paths.getIndexPath();
+        const indexDir = path.dirname(indexPath);
+        PathResolver.ensureDirectory(indexDir);
+        const messageCount = messages.length;
+        const indexEntries = summaries.map((entry) => ({
+            ...entry,
+            session_id: sessionId,
+            project: projectName,
+            message_count: entry.message_count || messageCount,
+            archive_path: archivePath,
+        }));
+        const indexContent = indexEntries.map((entry) => JSON.stringify(entry)).join('\n') + '\n';
+        fs.appendFileSync(indexPath, indexContent);
+        if (this.debugMode) {
+            log.debug(`📝 Appended ${indexEntries.length} entries to index`);
+            log.debug(`Index path: ${indexPath}`);
+        }
+    }
+}

package/dist/utils/common.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Common utilities for the memory compression system - CONSOLIDATED
+ *
+ * This module now re-exports the main utility classes to maintain backward compatibility.
+ * The duplicate implementations have been consolidated into the main utility files:
+ *
+ * - PathResolver -> src/utils/PathResolver.ts
+ * - SettingsManager -> src/utils/SettingsManager.ts
+ * - HookDetector -> src/utils/HookDetector.ts
+ */
+export { PathResolver } from './PathResolver.js';
+export { SettingsManager } from './SettingsManager.js';
+export { HookDetector } from './HookDetector.js';
+export type { SettingsLocation } from './PathResolver.js';
+export type { ClaudeSettings, SettingsResult } from './SettingsManager.js';
+export type { HookDetectionResult, HookInfo } from './HookDetector.js';
+export interface InstallOptions {
+    local?: boolean;
+    project?: boolean;
+    force?: boolean;
+}
+export interface ClaudeMemPaths {
+    baseDir: string;
+    hooksDir: string;
+    indexDir: string;
+    archivesDir: string;
+    logsDir: string;
+    settingsFile: string;
+}

package/dist/utils/common.js

@@ -0,0 +1,14 @@
+/**
+ * Common utilities for the memory compression system - CONSOLIDATED
+ *
+ * This module now re-exports the main utility classes to maintain backward compatibility.
+ * The duplicate implementations have been consolidated into the main utility files:
+ *
+ * - PathResolver -> src/utils/PathResolver.ts
+ * - SettingsManager -> src/utils/SettingsManager.ts
+ * - HookDetector -> src/utils/HookDetector.ts
+ */
+// Re-export main utility classes for backward compatibility
+export { PathResolver } from './PathResolver.js';
+export { SettingsManager } from './SettingsManager.js';
+export { HookDetector } from './HookDetector.js';