cccmemory 1.8.0

package/dist/ConversationMemory.js

@@ -0,0 +1,357 @@
+/**
+ * Main Orchestrator - Coordinates all components for conversation memory indexing and retrieval.
+ *
+ * ConversationMemory is the primary interface for the cccmemory-mcp system.
+ * It orchestrates parsing, storage, extraction, and search of Claude Code conversation history.
+ *
+ * @example
+ * ```typescript
+ * const memory = new ConversationMemory();
+ * await memory.indexConversations({
+ *   projectPath: '/path/to/project',
+ *   enableGitIntegration: true
+ * });
+ * ```
+ */
+import { getSQLiteManager } from "./storage/SQLiteManager.js";
+import { ConversationStorage } from "./storage/ConversationStorage.js";
+import { ConversationParser } from "./parsers/ConversationParser.js";
+import { DecisionExtractor } from "./parsers/DecisionExtractor.js";
+import { MistakeExtractor } from "./parsers/MistakeExtractor.js";
+import { GitIntegrator } from "./parsers/GitIntegrator.js";
+import { RequirementsExtractor } from "./parsers/RequirementsExtractor.js";
+import { SemanticSearch } from "./search/SemanticSearch.js";
+import { getWorktreeInfo } from "./utils/worktree.js";
+/**
+ * Main orchestrator for conversation memory operations.
+ *
+ * Coordinates parsing, storage, extraction, and search across:
+ * - Conversation parsing from JSONL files
+ * - Decision, mistake, and requirement extraction
+ * - Git commit integration
+ * - Semantic search with embeddings
+ */
+export class ConversationMemory {
+    sqliteManager;
+    storage;
+    parser;
+    decisionExtractor;
+    mistakeExtractor;
+    requirementsExtractor;
+    semanticSearch;
+    constructor() {
+        this.sqliteManager = getSQLiteManager();
+        this.storage = new ConversationStorage(this.sqliteManager);
+        // Enable caching by default for better performance
+        // Cache up to 100 query results for 5 minutes
+        this.storage.enableCache({ maxSize: 100, ttlMs: 300000 });
+        this.parser = new ConversationParser();
+        this.decisionExtractor = new DecisionExtractor();
+        this.mistakeExtractor = new MistakeExtractor();
+        this.requirementsExtractor = new RequirementsExtractor();
+        this.semanticSearch = new SemanticSearch(this.sqliteManager);
+    }
+    /**
+     * Index conversations for a project.
+     *
+     * This is the main entry point for processing conversation history.
+     * It performs the following operations:
+     * 1. Parse conversation JSONL files from the project
+     * 2. Store conversations, messages, and tool interactions
+     * 3. Extract decisions, mistakes, and requirements
+     * 4. Link git commits (if enabled)
+     * 5. Generate semantic embeddings for search
+     *
+     * @param options - Configuration options for indexing
+     * @returns Result object containing:
+     * - `embeddings_generated`: Whether embeddings were successfully generated
+     * - `embedding_error`: Error message if embedding generation failed
+     * - `indexed_folders`: List of folders that were indexed
+     * - `database_path`: Path to the SQLite database
+     *
+     * @throws {Error} If project path doesn't exist or conversation files can't be parsed
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.indexConversations({
+     *   projectPath: '/Users/me/my-project',
+     *   enableGitIntegration: true,
+     *   excludeMcpConversations: 'self-only'
+     * });
+     *
+     * if (result.embeddings_generated) {
+     *   console.error('Indexed folders:', result.indexed_folders);
+     * } else {
+     *   console.warn('Embeddings failed:', result.embedding_error);
+     * }
+     * ```
+     */
+    async indexConversations(options) {
+        const { canonicalPath, worktreePaths } = getWorktreeInfo(options.projectPath);
+        console.error("\n=== Indexing Conversations ===");
+        console.error(`Project: ${canonicalPath}`);
+        if (options.sessionId) {
+            console.error(`Session: ${options.sessionId} (single session mode)`);
+        }
+        else {
+            console.error(`Mode: All sessions`);
+        }
+        if (worktreePaths.length > 1) {
+            console.error(`Worktrees: ${worktreePaths.join(", ")}`);
+        }
+        // Parse conversations
+        let parseResult = this.parser.parseProjects(worktreePaths, options.sessionId, canonicalPath, options.lastIndexedMs);
+        // Filter MCP conversations if requested
+        if (options.excludeMcpConversations || options.excludeMcpServers) {
+            parseResult = this.filterMcpConversations(parseResult, options);
+        }
+        // Store basic entities (skip FTS rebuild for performance, will rebuild once at end)
+        await this.storage.storeConversations(parseResult.conversations);
+        await this.storage.storeMessages(parseResult.messages, true);
+        await this.storage.storeToolUses(parseResult.tool_uses);
+        await this.storage.storeToolResults(parseResult.tool_results);
+        await this.storage.storeFileEdits(parseResult.file_edits);
+        // Only store thinking blocks if explicitly enabled (default: false for privacy)
+        if (options.includeThinking === true) {
+            await this.storage.storeThinkingBlocks(parseResult.thinking_blocks);
+        }
+        // Extract decisions
+        console.error("\n=== Extracting Decisions ===");
+        const decisions = this.decisionExtractor.extractDecisions(parseResult.messages, parseResult.thinking_blocks);
+        await this.storage.storeDecisions(decisions, true);
+        // Rebuild FTS indexes once after all data is stored
+        this.storage.rebuildAllFts();
+        // Extract mistakes
+        console.error("\n=== Extracting Mistakes ===");
+        const mistakes = this.mistakeExtractor.extractMistakes(parseResult.messages, parseResult.tool_results);
+        await this.storage.storeMistakes(mistakes);
+        // Extract requirements and validations
+        console.error("\n=== Extracting Requirements ===");
+        const requirements = this.requirementsExtractor.extractRequirements(parseResult.messages);
+        await this.storage.storeRequirements(requirements);
+        const validations = this.requirementsExtractor.extractValidations(parseResult.tool_uses, parseResult.tool_results, parseResult.messages);
+        await this.storage.storeValidations(validations);
+        // Git integration
+        if (options.enableGitIntegration !== false) {
+            try {
+                console.error("\n=== Integrating Git History ===");
+                const gitIntegrator = new GitIntegrator(canonicalPath);
+                const commits = await gitIntegrator.linkCommitsToConversations(parseResult.conversations, parseResult.file_edits, decisions);
+                await this.storage.storeGitCommits(commits);
+                console.error(`✓ Linked ${commits.length} git commits`);
+            }
+            catch (error) {
+                console.error("⚠️ Git integration failed:", error);
+                console.error("  Conversations will be indexed without git commit links");
+                console.error("  This is normal if the project is not a git repository");
+            }
+        }
+        // Index for semantic search
+        console.error("\n=== Indexing for Semantic Search ===");
+        let embeddingError;
+        try {
+            await this.semanticSearch.indexMessages(parseResult.messages);
+            await this.semanticSearch.indexDecisions(decisions);
+            await this.semanticSearch.indexMistakes(mistakes);
+            // Also index any decisions/mistakes in DB that are missing embeddings
+            // (catches items created before embeddings were available)
+            await this.semanticSearch.indexMissingDecisionEmbeddings();
+            await this.semanticSearch.indexMissingMistakeEmbeddings();
+            console.error("✓ Semantic indexing complete");
+        }
+        catch (error) {
+            embeddingError = error.message;
+            console.error("⚠️ Semantic indexing failed:", error);
+            console.error("  Embeddings may not be available - falling back to full-text search");
+            console.error("  Install @xenova/transformers for semantic search: npm install @xenova/transformers");
+            // Don't throw - allow indexing to complete with FTS fallback
+        }
+        // Print stats
+        console.error("\n=== Indexing Complete ===");
+        const stats = this.storage.getStats();
+        console.error(`Conversations: ${stats.conversations.count}`);
+        console.error(`Messages: ${stats.messages.count}`);
+        console.error(`Decisions: ${stats.decisions.count}`);
+        console.error(`Mistakes: ${stats.mistakes.count}`);
+        console.error(`Git Commits: ${stats.git_commits.count}`);
+        // Return embedding status and indexing metadata
+        return {
+            embeddings_generated: !embeddingError,
+            embedding_error: embeddingError,
+            indexed_folders: parseResult.indexed_folders,
+            database_path: this.sqliteManager.getDbPath(),
+        };
+    }
+    /**
+     * Search conversations using natural language query.
+     *
+     * Uses semantic search with embeddings if available, otherwise falls back to full-text search.
+     *
+     * @param query - Natural language search query
+     * @param limit - Maximum number of results to return (default: 10)
+     * @returns Array of search results with messages, conversations, and similarity scores
+     *
+     * @example
+     * ```typescript
+     * const results = await memory.search('authentication bug fix', 5);
+     * results.forEach(r => {
+     *   console.error(`${r.similarity}: ${r.snippet}`);
+     * });
+     * ```
+     */
+    async search(query, limit = 10) {
+        return this.semanticSearch.searchConversations(query, limit);
+    }
+    /**
+     * Search for decisions using natural language query.
+     *
+     * Searches through extracted decisions to find relevant architectural choices and technical decisions.
+     *
+     * @param query - Natural language search query
+     * @param limit - Maximum number of results to return (default: 10)
+     * @returns Array of decision search results with similarity scores
+     *
+     * @example
+     * ```typescript
+     * const decisions = await memory.searchDecisions('database choice', 3);
+     * decisions.forEach(d => {
+     *   console.error(`Decision: ${d.decision.decision_text}`);
+     *   console.error(`Rationale: ${d.decision.rationale}`);
+     * });
+     * ```
+     */
+    async searchDecisions(query, limit = 10) {
+        return this.semanticSearch.searchDecisions(query, limit);
+    }
+    /**
+     * Get the timeline of changes for a specific file.
+     *
+     * Returns all edits, commits, and related conversations for a file across its history.
+     *
+     * @param filePath - Path to the file (relative to project root)
+     * @returns Timeline of file changes with conversations and commits
+     *
+     * @example
+     * ```typescript
+     * const timeline = memory.getFileTimeline('src/index.ts');
+     * console.error(`${timeline.length} changes to this file`);
+     * ```
+     */
+    getFileTimeline(filePath) {
+        return this.storage.getFileTimeline(filePath);
+    }
+    /**
+     * Get statistics about the indexed conversation data.
+     *
+     * @returns Object containing counts for conversations, messages, decisions, mistakes, and commits
+     *
+     * @example
+     * ```typescript
+     * const stats = memory.getStats();
+     * console.error(`Indexed ${stats.conversations.count} conversations`);
+     * console.error(`Extracted ${stats.decisions.count} decisions`);
+     * ```
+     */
+    getStats() {
+        return this.storage.getStats();
+    }
+    /**
+     * Get the underlying storage instance for direct database access.
+     *
+     * Use with caution - prefer using the high-level methods when possible.
+     *
+     * @returns ConversationStorage instance
+     * @internal
+     */
+    getStorage() {
+        return this.storage;
+    }
+    /**
+     * Get the semantic search instance for advanced search operations.
+     *
+     * @returns SemanticSearch instance
+     * @internal
+     */
+    getSemanticSearch() {
+        return this.semanticSearch;
+    }
+    /**
+     * Filter MCP conversations from parse results.
+     *
+     * Implements the exclusion logic for MCP tool conversations to prevent
+     * self-referential loops and reduce noise in the index.
+     *
+     * Strategy: Filter at MESSAGE level, not conversation level.
+     * - Keep all conversations
+     * - Exclude only messages that invoke specified MCP tools and their responses
+     */
+    filterMcpConversations(result, options) {
+        // Determine which MCP servers to exclude
+        const serversToExclude = new Set();
+        if (options.excludeMcpServers && options.excludeMcpServers.length > 0) {
+            // Explicit list of servers to exclude
+            options.excludeMcpServers.forEach(s => serversToExclude.add(s));
+        }
+        else if (options.excludeMcpConversations === 'self-only') {
+            // Exclude only cccmemory server
+            serversToExclude.add('cccmemory');
+        }
+        else if (options.excludeMcpConversations === 'all-mcp' || options.excludeMcpConversations === true) {
+            // Exclude all MCP tool uses - collect all server names from tool uses
+            for (const toolUse of result.tool_uses) {
+                if (toolUse.tool_name.startsWith('mcp__')) {
+                    const parts = toolUse.tool_name.split('__');
+                    if (parts.length >= 2) {
+                        serversToExclude.add(parts[1]);
+                    }
+                }
+            }
+        }
+        if (serversToExclude.size === 0) {
+            return result; // Nothing to filter
+        }
+        // Build set of excluded tool_use IDs (tools from excluded servers)
+        const excludedToolUseIds = new Set();
+        for (const toolUse of result.tool_uses) {
+            if (toolUse.tool_name.startsWith('mcp__')) {
+                const parts = toolUse.tool_name.split('__');
+                if (parts.length >= 2 && serversToExclude.has(parts[1])) {
+                    excludedToolUseIds.add(toolUse.id);
+                }
+            }
+        }
+        // Build set of excluded message IDs (messages containing excluded tool uses or their results)
+        const excludedMessageIds = new Set();
+        // Exclude assistant messages that contain excluded tool uses
+        for (const toolUse of result.tool_uses) {
+            if (excludedToolUseIds.has(toolUse.id)) {
+                excludedMessageIds.add(toolUse.message_id);
+            }
+        }
+        // Exclude user messages that contain tool results for excluded tool uses
+        for (const toolResult of result.tool_results) {
+            if (excludedToolUseIds.has(toolResult.tool_use_id)) {
+                excludedMessageIds.add(toolResult.message_id);
+            }
+        }
+        if (excludedMessageIds.size > 0) {
+            console.error(`\n⚠️ Excluding ${excludedMessageIds.size} message(s) containing MCP tool calls from: ${Array.from(serversToExclude).join(', ')}`);
+        }
+        // Build set of remaining message IDs after filtering
+        const remainingMessageIds = new Set(result.messages
+            .filter(m => !excludedMessageIds.has(m.id))
+            .map(m => m.id));
+        // Filter messages and related entities
+        // IMPORTANT: file_edits must also be filtered to avoid FK constraint violations
+        return {
+            conversations: result.conversations, // Keep ALL conversations
+            messages: result.messages.filter(m => !excludedMessageIds.has(m.id)),
+            tool_uses: result.tool_uses.filter(t => !excludedToolUseIds.has(t.id)),
+            tool_results: result.tool_results.filter(tr => !excludedToolUseIds.has(tr.tool_use_id)),
+            file_edits: result.file_edits.filter(fe => remainingMessageIds.has(fe.message_id)),
+            thinking_blocks: result.thinking_blocks.filter(tb => remainingMessageIds.has(tb.message_id)),
+            indexed_folders: result.indexed_folders, // Preserve folder metadata
+        };
+    }
+}
+//# sourceMappingURL=ConversationMemory.js.map

package/dist/ConversationMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationMemory.js","sourceRoot":"","sources":["../src/ConversationMemory.ts"],"names":[],"mappings":"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"}

package/dist/cache/QueryCache.d.ts

@@ -0,0 +1,215 @@
+/**
+ * QueryCache - LRU cache for database query results
+ *
+ * Provides an in-memory caching layer with:
+ * - LRU (Least Recently Used) eviction policy
+ * - TTL (Time To Live) for automatic expiration
+ * - Cache statistics (hits, misses, evictions, hit rate)
+ * - Smart invalidation support
+ *
+ * Use this to cache expensive database queries like conversation searches,
+ * file timelines, and decision lookups.
+ *
+ * @example
+ * ```typescript
+ * const cache = new QueryCache({ maxSize: 100, ttlMs: 60000 });
+ *
+ * // Store query result
+ * cache.set('conversations:all', conversations);
+ *
+ * // Retrieve from cache
+ * const cached = cache.get('conversations:all');
+ * if (cached) {
+ *   return cached; // Cache hit
+ * }
+ *
+ * // Cache miss - query database
+ * const result = await queryDatabase();
+ * cache.set('conversations:all', result);
+ * return result;
+ * ```
+ */
+/**
+ * Configuration options for QueryCache
+ */
+export interface QueryCacheConfig {
+    /** Maximum number of entries to store */
+    maxSize: number;
+    /** Time to live in milliseconds before entries expire */
+    ttlMs: number;
+}
+/**
+ * Cache statistics for monitoring
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of entries evicted */
+    evictions: number;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Current cache size */
+    size: number;
+    /** Maximum cache size */
+    maxSize: number;
+}
+/**
+ * LRU cache with TTL support for database query results.
+ *
+ * Uses a Map for O(1) access and maintains LRU order by moving
+ * accessed entries to the end of the Map.
+ */
+export declare class QueryCache {
+    private cache;
+    private readonly config;
+    private stats;
+    /**
+     * Create a new QueryCache.
+     *
+     * @param config - Cache configuration
+     * @throws {Error} If configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * // Create cache with 100 entries, 1 minute TTL
+     * const cache = new QueryCache({ maxSize: 100, ttlMs: 60000 });
+     * ```
+     */
+    constructor(config?: Partial<QueryCacheConfig>);
+    /**
+     * Store a value in the cache.
+     *
+     * If the key already exists, updates the value and resets TTL.
+     * If cache is full, evicts the least recently used entry.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     *
+     * @example
+     * ```typescript
+     * cache.set('user:123', { id: 123, name: 'Alice' });
+     * ```
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Retrieve a value from the cache.
+     *
+     * Returns undefined if key doesn't exist or entry has expired.
+     * Updates access order (moves entry to end as most recently used).
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined
+     *
+     * @example
+     * ```typescript
+     * const user = cache.get<User>('user:123');
+     * if (user) {
+     *   console.log('Cache hit:', user.name);
+     * } else {
+     *   console.log('Cache miss');
+     * }
+     * ```
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Check if a key exists in the cache.
+     *
+     * Returns false if key doesn't exist or entry has expired.
+     * Updates access order (moves entry to end as most recently used).
+     *
+     * @param key - Cache key
+     * @returns True if key exists and not expired
+     *
+     * @example
+     * ```typescript
+     * if (cache.has('user:123')) {
+     *   const user = cache.get('user:123');
+     * }
+     * ```
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from the cache.
+     *
+     * Does nothing if key doesn't exist.
+     *
+     * @param key - Cache key to delete
+     *
+     * @example
+     * ```typescript
+     * cache.delete('user:123');
+     * ```
+     */
+    delete(key: string): void;
+    /**
+     * Clear all entries from the cache.
+     *
+     * Resets the cache but preserves statistics.
+     *
+     * @example
+     * ```typescript
+     * cache.clear(); // Remove all cached data
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get current cache size.
+     *
+     * @returns Number of entries in cache
+     *
+     * @example
+     * ```typescript
+     * console.log(`Cache contains ${cache.size()} entries`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Get cache statistics.
+     *
+     * Provides insight into cache performance:
+     * - Hit/miss counts
+     * - Hit rate percentage
+     * - Eviction count
+     * - Current size
+     *
+     * @returns Cache statistics object
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getStats();
+     * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+     * console.log(`Evictions: ${stats.evictions}`);
+     * ```
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics counters.
+     *
+     * Clears hit/miss/eviction counts but preserves cached data.
+     *
+     * @example
+     * ```typescript
+     * cache.resetStats(); // Start fresh statistics
+     * ```
+     */
+    resetStats(): void;
+    /**
+     * Check if an entry has expired based on TTL.
+     *
+     * @param entry - Cache entry to check
+     * @returns True if entry is expired
+     * @internal
+     */
+    private isExpired;
+    /**
+     * Remove all expired entries from the cache.
+     *
+     * Called automatically by size() to keep cache clean.
+     *
+     * @internal
+     */
+    private cleanupExpired;
+}
+//# sourceMappingURL=QueryCache.d.ts.map

package/dist/cache/QueryCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryCache.d.ts","sourceRoot":"","sources":["../../src/cache/QueryCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAYD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,KAAK,CAIX;IAEF;;;;;;;;;;;OAWG;gBACS,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAkBlD;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAsBnC;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAuBlC;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAoBzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;OASG;IACH,IAAI,IAAI,MAAM;IAMd;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,IAAI,UAAU;IActB;;;;;;;;;OASG;IACH,UAAU,IAAI,IAAI;IAQlB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAavB"}