cccmemory 1.8.0

package/dist/storage/ConversationStorage.js

@@ -0,0 +1,792 @@
+/**
+ * Conversation Storage Layer - CRUD operations for all conversation-related data.
+ *
+ * This class provides the data access layer for the cccmemory system.
+ * It handles storing and retrieving conversations, messages, tool uses, decisions,
+ * mistakes, requirements, and git commits.
+ *
+ * All store operations use transactions for atomicity and performance.
+ * All JSON fields are automatically serialized/deserialized.
+ *
+ * @example
+ * ```typescript
+ * const storage = new ConversationStorage(sqliteManager);
+ * await storage.storeConversations(conversations);
+ * const conv = storage.getConversation('conv-123');
+ * const timeline = storage.getFileTimeline('src/index.ts');
+ * ```
+ */
+import { sanitizeForLike } from "../utils/sanitization.js";
+import { QueryCache } from "../cache/QueryCache.js";
+import { safeJsonParse } from "../utils/safeJson.js";
+/**
+ * Data access layer for conversation memory storage.
+ *
+ * Provides CRUD operations for all conversation-related entities using SQLite.
+ * Supports optional caching for frequently accessed queries.
+ */
+export class ConversationStorage {
+    db;
+    cache = null;
+    /**
+     * Create a new ConversationStorage instance.
+     *
+     * @param db - SQLiteManager instance for database access
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    // ==================== Cache Management ====================
+    /**
+     * Enable query result caching.
+     *
+     * Caching improves performance for frequently accessed queries by storing
+     * results in memory. Cache is automatically invalidated when data changes.
+     *
+     * @param config - Cache configuration (maxSize and ttlMs)
+     *
+     * @example
+     * ```typescript
+     * storage.enableCache({ maxSize: 100, ttlMs: 300000 });
+     * ```
+     */
+    enableCache(config) {
+        this.cache = new QueryCache(config);
+    }
+    /**
+     * Disable query result caching.
+     *
+     * Clears all cached data and stops caching new queries.
+     */
+    disableCache() {
+        this.cache = null;
+    }
+    /**
+     * Check if caching is enabled.
+     *
+     * @returns True if caching is enabled
+     */
+    isCacheEnabled() {
+        return this.cache !== null;
+    }
+    /**
+     * Clear all cached query results.
+     *
+     * Clears the cache but keeps caching enabled.
+     */
+    clearCache() {
+        if (this.cache) {
+            this.cache.clear();
+            this.cache.resetStats();
+        }
+    }
+    /**
+     * Get cache statistics.
+     *
+     * Returns performance metrics including hits, misses, hit rate, and evictions.
+     *
+     * @returns Cache statistics or null if caching is disabled
+     *
+     * @example
+     * ```typescript
+     * const stats = storage.getCacheStats();
+     * if (stats) {
+     *   console.error(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+     * }
+     * ```
+     */
+    getCacheStats() {
+        return this.cache ? this.cache.getStats() : null;
+    }
+    // ==================== Conversations ====================
+    /**
+     * Store conversations in the database.
+     *
+     * Uses UPSERT (INSERT ON CONFLICT UPDATE) to handle both new and updated conversations.
+     * All operations are performed in a single transaction for atomicity.
+     *
+     * @param conversations - Array of conversation objects to store
+     * @returns Promise that resolves when all conversations are stored
+     *
+     * @example
+     * ```typescript
+     * await storage.storeConversations([
+     *   {
+     *     id: 'conv-123',
+     *     project_path: '/path/to/project',
+     *     first_message_at: Date.now(),
+     *     last_message_at: Date.now(),
+     *     message_count: 42,
+     *     git_branch: 'main',
+     *     claude_version: '3.5',
+     *     metadata: {},
+     *     created_at: Date.now(),
+     *     updated_at: Date.now()
+     *   }
+     * ]);
+     * ```
+     */
+    async storeConversations(conversations) {
+        const stmt = this.db.prepare(`
+      INSERT INTO conversations
+      (id, project_path, source_type, first_message_at, last_message_at, message_count,
+       git_branch, claude_version, metadata, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        project_path = excluded.project_path,
+        source_type = excluded.source_type,
+        first_message_at = excluded.first_message_at,
+        last_message_at = excluded.last_message_at,
+        message_count = excluded.message_count,
+        git_branch = excluded.git_branch,
+        claude_version = excluded.claude_version,
+        metadata = excluded.metadata,
+        updated_at = excluded.updated_at
+    `);
+        this.db.transaction(() => {
+            for (const conv of conversations) {
+                stmt.run(conv.id, conv.project_path, conv.source_type || 'claude-code', conv.first_message_at, conv.last_message_at, conv.message_count, conv.git_branch, conv.claude_version, JSON.stringify(conv.metadata), conv.created_at, conv.updated_at);
+            }
+        });
+        // Invalidate cache once after batch (not per-item)
+        if (this.cache) {
+            this.cache.clear();
+        }
+        console.error(`✓ Stored ${conversations.length} conversations`);
+    }
+    /**
+     * Retrieve a single conversation by ID.
+     *
+     * @param id - Conversation ID to retrieve
+     * @returns Conversation object if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const conv = storage.getConversation('conv-123');
+     * if (conv) {
+     *   console.error(`${conv.message_count} messages on ${conv.git_branch}`);
+     * }
+     * ```
+     */
+    getConversation(id) {
+        const cacheKey = `conversation:${id}`;
+        // Check cache first
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        const row = this.db
+            .prepare("SELECT * FROM conversations WHERE id = ?")
+            .get(id);
+        if (!row) {
+            // Cache null result to avoid repeated queries
+            this.cache?.set(cacheKey, null);
+            return null;
+        }
+        const result = {
+            ...row,
+            metadata: safeJsonParse(row.metadata, {}),
+        };
+        // Cache the result
+        this.cache?.set(cacheKey, result);
+        return result;
+    }
+    // ==================== Messages ====================
+    /**
+     * Store messages in the database.
+     *
+     * Stores all messages from conversations including content, metadata, and relationships.
+     * Uses UPSERT (INSERT ON CONFLICT UPDATE) for idempotent storage.
+     *
+     * @param messages - Array of message objects to store
+     * @param skipFtsRebuild - Skip FTS rebuild (for batch operations, call rebuildAllFts() at end)
+     * @returns Promise that resolves when all messages are stored
+     *
+     * @example
+     * ```typescript
+     * await storage.storeMessages([
+     *   {
+     *     id: 'msg-123',
+     *     conversation_id: 'conv-123',
+     *     message_type: 'text',
+     *     role: 'user',
+     *     content: 'Hello',
+     *     timestamp: Date.now(),
+     *     is_sidechain: false,
+     *     metadata: {}
+     *   }
+     * ]);
+     * ```
+     */
+    async storeMessages(messages, skipFtsRebuild = false) {
+        const stmt = this.db.prepare(`
+      INSERT INTO messages
+      (id, conversation_id, parent_id, message_type, role, content,
+       timestamp, is_sidechain, agent_id, request_id, git_branch, cwd, metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        conversation_id = excluded.conversation_id,
+        parent_id = excluded.parent_id,
+        message_type = excluded.message_type,
+        role = excluded.role,
+        content = excluded.content,
+        timestamp = excluded.timestamp,
+        is_sidechain = excluded.is_sidechain,
+        agent_id = excluded.agent_id,
+        request_id = excluded.request_id,
+        git_branch = excluded.git_branch,
+        cwd = excluded.cwd,
+        metadata = excluded.metadata
+    `);
+        // Build a set of message IDs for FK validation (from current batch)
+        const messageIds = new Set(messages.map(m => m.id));
+        // Collect parent_ids that need DB lookup (not in current batch)
+        const parentIdsToCheck = new Set();
+        for (const msg of messages) {
+            if (msg.parent_id && !messageIds.has(msg.parent_id)) {
+                parentIdsToCheck.add(msg.parent_id);
+            }
+        }
+        // Only query DB for specific parent_ids we need (O(k) where k = unique parent refs)
+        // Chunk to avoid SQLite's max variables limit (999 by default)
+        if (parentIdsToCheck.size > 0) {
+            const CHUNK_SIZE = 500; // Stay well under SQLite's limit
+            const parentIdsArray = Array.from(parentIdsToCheck);
+            for (let i = 0; i < parentIdsArray.length; i += CHUNK_SIZE) {
+                const chunk = parentIdsArray.slice(i, i + CHUNK_SIZE);
+                const placeholders = chunk.map(() => '?').join(',');
+                const existingIds = this.db
+                    .prepare(`SELECT id FROM messages WHERE id IN (${placeholders})`)
+                    .all(...chunk);
+                for (const row of existingIds) {
+                    messageIds.add(row.id);
+                }
+            }
+        }
+        this.db.transaction(() => {
+            for (const msg of messages) {
+                // Nullify parent_id if it references a non-existent message to avoid FK violation
+                const safeParentId = msg.parent_id && messageIds.has(msg.parent_id) ? msg.parent_id : null;
+                stmt.run(msg.id, msg.conversation_id, safeParentId, msg.message_type, msg.role || null, msg.content || null, msg.timestamp, msg.is_sidechain ? 1 : 0, msg.agent_id || null, msg.request_id || null, msg.git_branch || null, msg.cwd || null, JSON.stringify(msg.metadata));
+            }
+        });
+        // Rebuild FTS index for full-text search
+        // FTS5 with external content requires explicit rebuild after inserts
+        // Skip during batch operations for performance (call rebuildAllFts() at end)
+        if (!skipFtsRebuild) {
+            this.rebuildMessagesFts();
+        }
+        console.error(`✓ Stored ${messages.length} messages`);
+    }
+    /**
+     * Rebuild the messages FTS index.
+     * Required for FTS5 external content tables after inserting data.
+     * Call this after batch operations that used skipFtsRebuild=true.
+     */
+    rebuildMessagesFts() {
+        try {
+            this.db.getDatabase().exec("INSERT INTO messages_fts(messages_fts) VALUES('rebuild')");
+        }
+        catch (error) {
+            // FTS rebuild may fail if table doesn't exist or schema mismatch
+            // Log but don't throw - FTS is optional fallback
+            console.error("FTS rebuild warning:", error.message);
+        }
+    }
+    // ==================== Tool Uses ====================
+    /**
+     * Store tool use records in the database.
+     *
+     * Records all tool invocations from assistant messages.
+     *
+     * @param toolUses - Array of tool use objects
+     * @returns Promise that resolves when stored
+     */
+    async storeToolUses(toolUses) {
+        const stmt = this.db.prepare(`
+      INSERT INTO tool_uses
+      (id, message_id, tool_name, tool_input, timestamp)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        message_id = excluded.message_id,
+        tool_name = excluded.tool_name,
+        tool_input = excluded.tool_input,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const tool of toolUses) {
+                stmt.run(tool.id, tool.message_id, tool.tool_name, JSON.stringify(tool.tool_input), tool.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${toolUses.length} tool uses`);
+    }
+    // ==================== Tool Results ====================
+    /**
+     * Store tool execution results in the database.
+     *
+     * Records the output/results from tool invocations.
+     *
+     * @param toolResults - Array of tool result objects
+     * @returns Promise that resolves when stored
+     */
+    async storeToolResults(toolResults) {
+        const stmt = this.db.prepare(`
+      INSERT INTO tool_results
+      (id, tool_use_id, message_id, content, is_error, stdout, stderr, is_image, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        tool_use_id = excluded.tool_use_id,
+        message_id = excluded.message_id,
+        content = excluded.content,
+        is_error = excluded.is_error,
+        stdout = excluded.stdout,
+        stderr = excluded.stderr,
+        is_image = excluded.is_image,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const result of toolResults) {
+                stmt.run(result.id, result.tool_use_id, result.message_id, result.content || null, result.is_error ? 1 : 0, result.stdout || null, result.stderr || null, result.is_image ? 1 : 0, result.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${toolResults.length} tool results`);
+    }
+    // ==================== File Edits ====================
+    /**
+     * Store file edit records in the database.
+     *
+     * Records all file modifications made during conversations.
+     *
+     * @param fileEdits - Array of file edit objects
+     * @returns Promise that resolves when stored
+     */
+    async storeFileEdits(fileEdits) {
+        const stmt = this.db.prepare(`
+      INSERT INTO file_edits
+      (id, conversation_id, file_path, message_id, backup_version,
+       backup_time, snapshot_timestamp, metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        conversation_id = excluded.conversation_id,
+        file_path = excluded.file_path,
+        message_id = excluded.message_id,
+        backup_version = excluded.backup_version,
+        backup_time = excluded.backup_time,
+        snapshot_timestamp = excluded.snapshot_timestamp,
+        metadata = excluded.metadata
+    `);
+        this.db.transaction(() => {
+            for (const edit of fileEdits) {
+                stmt.run(edit.id, edit.conversation_id, edit.file_path, edit.message_id, edit.backup_version || null, edit.backup_time || null, edit.snapshot_timestamp, JSON.stringify(edit.metadata));
+                // Invalidate all caches for this file
+                if (this.cache) {
+                    this.cache.delete(`edits:${edit.file_path}`);
+                    this.cache.delete(`timeline:${edit.file_path}`);
+                }
+            }
+        });
+        console.error(`✓ Stored ${fileEdits.length} file edits`);
+    }
+    /**
+     * Retrieve all edits for a specific file.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file edits, ordered by timestamp (most recent first)
+     */
+    getFileEdits(filePath) {
+        const cacheKey = `edits:${filePath}`;
+        // Check cache first
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        const rows = this.db
+            .prepare("SELECT * FROM file_edits WHERE file_path = ? ORDER BY snapshot_timestamp DESC")
+            .all(filePath);
+        // Parse metadata JSON for each row
+        const result = rows.map(row => ({
+            ...row,
+            metadata: safeJsonParse(row.metadata, {}),
+        }));
+        // Cache the result
+        this.cache?.set(cacheKey, result);
+        return result;
+    }
+    // ==================== Thinking Blocks ====================
+    /**
+     * Store thinking blocks in the database.
+     *
+     * Thinking blocks contain Claude's internal reasoning. They can be large and
+     * are optionally indexed based on the includeThinking flag.
+     *
+     * @param blocks - Array of thinking block objects
+     * @returns Promise that resolves when stored
+     */
+    async storeThinkingBlocks(blocks) {
+        const stmt = this.db.prepare(`
+      INSERT INTO thinking_blocks
+      (id, message_id, thinking_content, signature, timestamp)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        message_id = excluded.message_id,
+        thinking_content = excluded.thinking_content,
+        signature = excluded.signature,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const block of blocks) {
+                stmt.run(block.id, block.message_id, block.thinking_content, block.signature || null, block.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${blocks.length} thinking blocks`);
+    }
+    // ==================== Decisions ====================
+    /**
+     * Store extracted decisions in the database.
+     *
+     * Decisions include architectural choices, technical decisions, and their rationale.
+     *
+     * @param decisions - Array of decision objects
+     * @param skipFtsRebuild - Skip FTS rebuild (for batch operations, call rebuildAllFts() at end)
+     * @returns Promise that resolves when stored
+     */
+    async storeDecisions(decisions, skipFtsRebuild = false) {
+        const stmt = this.db.prepare(`
+      INSERT INTO decisions
+      (id, conversation_id, message_id, decision_text, rationale,
+       alternatives_considered, rejected_reasons, context, related_files,
+       related_commits, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        conversation_id = excluded.conversation_id,
+        message_id = excluded.message_id,
+        decision_text = excluded.decision_text,
+        rationale = excluded.rationale,
+        alternatives_considered = excluded.alternatives_considered,
+        rejected_reasons = excluded.rejected_reasons,
+        context = excluded.context,
+        related_files = excluded.related_files,
+        related_commits = excluded.related_commits,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const decision of decisions) {
+                stmt.run(decision.id, decision.conversation_id, decision.message_id, decision.decision_text, decision.rationale || null, JSON.stringify(decision.alternatives_considered), JSON.stringify(decision.rejected_reasons), decision.context || null, JSON.stringify(decision.related_files), JSON.stringify(decision.related_commits), decision.timestamp);
+                // Invalidate caches for related files
+                if (this.cache && decision.related_files) {
+                    for (const filePath of decision.related_files) {
+                        this.cache.delete(`decisions:${filePath}`);
+                        this.cache.delete(`timeline:${filePath}`);
+                    }
+                }
+            }
+        });
+        // Rebuild FTS index for full-text search
+        // FTS5 with external content requires explicit rebuild after inserts
+        // Skip during batch operations for performance (call rebuildAllFts() at end)
+        if (!skipFtsRebuild) {
+            this.rebuildDecisionsFts();
+        }
+        console.error(`✓ Stored ${decisions.length} decisions`);
+    }
+    /**
+     * Rebuild the decisions FTS index.
+     * Required for FTS5 external content tables after inserting data.
+     * Call this after batch operations that used skipFtsRebuild=true.
+     */
+    rebuildDecisionsFts() {
+        try {
+            this.db.getDatabase().exec("INSERT INTO decisions_fts(decisions_fts) VALUES('rebuild')");
+        }
+        catch (error) {
+            // FTS rebuild may fail if table doesn't exist or schema mismatch
+            // Log but don't throw - FTS is optional fallback
+            console.error("FTS decisions rebuild warning:", error.message);
+        }
+    }
+    /**
+     * Rebuild all FTS indexes.
+     * Call this once after batch operations that used skipFtsRebuild=true.
+     */
+    rebuildAllFts() {
+        this.rebuildMessagesFts();
+        this.rebuildDecisionsFts();
+    }
+    /**
+     * Retrieve all decisions related to a specific file.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of decisions that reference this file
+     * @internal
+     */
+    getDecisionsForFile(filePath) {
+        const cacheKey = `decisions:${filePath}`;
+        // Check cache first
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        const sanitized = sanitizeForLike(filePath);
+        const rows = this.db
+            .prepare("SELECT * FROM decisions WHERE related_files LIKE ? ESCAPE '\\' ORDER BY timestamp DESC")
+            .all(`%"${sanitized}"%`);
+        const result = rows.map((row) => ({
+            ...row,
+            alternatives_considered: safeJsonParse(row.alternatives_considered, []),
+            rejected_reasons: safeJsonParse(row.rejected_reasons, {}),
+            related_files: safeJsonParse(row.related_files, []),
+            related_commits: safeJsonParse(row.related_commits, []),
+        }));
+        // Cache the result
+        this.cache?.set(cacheKey, result);
+        return result;
+    }
+    // ==================== Git Commits ====================
+    /**
+     * Store git commit records linked to conversations.
+     *
+     * Links git commits to the conversations where they were made or discussed.
+     *
+     * @param commits - Array of git commit objects
+     * @returns Promise that resolves when stored
+     */
+    async storeGitCommits(commits) {
+        const stmt = this.db.prepare(`
+      INSERT INTO git_commits
+      (hash, message, author, timestamp, branch, files_changed,
+       conversation_id, related_message_id, metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(hash) DO UPDATE SET
+        message = excluded.message,
+        author = excluded.author,
+        timestamp = excluded.timestamp,
+        branch = excluded.branch,
+        files_changed = excluded.files_changed,
+        conversation_id = excluded.conversation_id,
+        related_message_id = excluded.related_message_id,
+        metadata = excluded.metadata
+    `);
+        this.db.transaction(() => {
+            for (const commit of commits) {
+                stmt.run(commit.hash, commit.message, commit.author || null, commit.timestamp, commit.branch || null, JSON.stringify(commit.files_changed), commit.conversation_id || null, commit.related_message_id || null, JSON.stringify(commit.metadata));
+                // Invalidate caches for affected files
+                if (this.cache && commit.files_changed) {
+                    for (const filePath of commit.files_changed) {
+                        this.cache.delete(`commits:${filePath}`);
+                        this.cache.delete(`timeline:${filePath}`);
+                    }
+                }
+            }
+        });
+        console.error(`✓ Stored ${commits.length} git commits`);
+    }
+    getCommitsForFile(filePath) {
+        const cacheKey = `commits:${filePath}`;
+        // Check cache first
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        const sanitized = sanitizeForLike(filePath);
+        const rows = this.db
+            .prepare("SELECT * FROM git_commits WHERE files_changed LIKE ? ESCAPE '\\' ORDER BY timestamp DESC")
+            .all(`%"${sanitized}"%`);
+        const result = rows.map((row) => ({
+            ...row,
+            files_changed: safeJsonParse(row.files_changed, []),
+            metadata: safeJsonParse(row.metadata, {}),
+        }));
+        // Cache the result
+        this.cache?.set(cacheKey, result);
+        return result;
+    }
+    // ==================== Mistakes ====================
+    /**
+     * Store extracted mistakes in the database.
+     *
+     * Mistakes include errors, bugs, and wrong approaches that were later corrected.
+     *
+     * @param mistakes - Array of mistake objects
+     * @returns Promise that resolves when stored
+     */
+    async storeMistakes(mistakes) {
+        const stmt = this.db.prepare(`
+      INSERT INTO mistakes
+      (id, conversation_id, message_id, mistake_type, what_went_wrong,
+       correction, user_correction_message, files_affected, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        conversation_id = excluded.conversation_id,
+        message_id = excluded.message_id,
+        mistake_type = excluded.mistake_type,
+        what_went_wrong = excluded.what_went_wrong,
+        correction = excluded.correction,
+        user_correction_message = excluded.user_correction_message,
+        files_affected = excluded.files_affected,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const mistake of mistakes) {
+                stmt.run(mistake.id, mistake.conversation_id, mistake.message_id, mistake.mistake_type, mistake.what_went_wrong, mistake.correction || null, mistake.user_correction_message || null, JSON.stringify(mistake.files_affected), mistake.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${mistakes.length} mistakes`);
+    }
+    // ==================== Requirements ====================
+    /**
+     * Store extracted requirements in the database.
+     *
+     * Requirements include dependencies, constraints, and specifications for components.
+     *
+     * @param requirements - Array of requirement objects
+     * @returns Promise that resolves when stored
+     */
+    async storeRequirements(requirements) {
+        const stmt = this.db.prepare(`
+      INSERT INTO requirements
+      (id, type, description, rationale, affects_components,
+       conversation_id, message_id, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        type = excluded.type,
+        description = excluded.description,
+        rationale = excluded.rationale,
+        affects_components = excluded.affects_components,
+        conversation_id = excluded.conversation_id,
+        message_id = excluded.message_id,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const req of requirements) {
+                stmt.run(req.id, req.type, req.description, req.rationale || null, JSON.stringify(req.affects_components), req.conversation_id, req.message_id, req.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${requirements.length} requirements`);
+    }
+    // ==================== Validations ====================
+    /**
+     * Store validation records in the database.
+     *
+     * Validations capture test results and performance data from conversations.
+     *
+     * @param validations - Array of validation objects
+     * @returns Promise that resolves when stored
+     */
+    async storeValidations(validations) {
+        const stmt = this.db.prepare(`
+      INSERT INTO validations
+      (id, conversation_id, what_was_tested, test_command, result,
+       performance_data, files_tested, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        conversation_id = excluded.conversation_id,
+        what_was_tested = excluded.what_was_tested,
+        test_command = excluded.test_command,
+        result = excluded.result,
+        performance_data = excluded.performance_data,
+        files_tested = excluded.files_tested,
+        timestamp = excluded.timestamp
+    `);
+        this.db.transaction(() => {
+            for (const val of validations) {
+                stmt.run(val.id, val.conversation_id, val.what_was_tested, val.test_command || null, val.result, val.performance_data ? JSON.stringify(val.performance_data) : null, JSON.stringify(val.files_tested), val.timestamp);
+            }
+        });
+        console.error(`✓ Stored ${validations.length} validations`);
+    }
+    // ==================== Queries ====================
+    /**
+     * Get the complete timeline of changes to a file.
+     *
+     * Combines file edits, git commits, and related decisions into a single timeline.
+     * This is a key method used by tools like checkBeforeModify and getFileEvolution.
+     *
+     * @param filePath - Path to the file
+     * @returns Object containing:
+     * - `file_path`: The file path queried
+     * - `edits`: All file edit records
+     * - `commits`: All git commits affecting this file
+     * - `decisions`: All decisions related to this file
+     *
+     * @example
+     * ```typescript
+     * const timeline = storage.getFileTimeline('src/index.ts');
+     * console.error(`${timeline.edits.length} edits`);
+     * console.error(`${timeline.commits.length} commits`);
+     * console.error(`${timeline.decisions.length} decisions`);
+     * ```
+     */
+    getFileTimeline(filePath) {
+        const cacheKey = `timeline:${filePath}`;
+        // Check cache first
+        if (this.cache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // Combine file edits, commits, and decisions
+        const edits = this.getFileEdits(filePath);
+        const commits = this.getCommitsForFile(filePath);
+        const decisions = this.getDecisionsForFile(filePath);
+        const result = {
+            file_path: filePath,
+            edits,
+            commits,
+            decisions,
+        };
+        // Cache the result
+        this.cache?.set(cacheKey, result);
+        return result;
+    }
+    /**
+     * Get statistics about the indexed conversation data.
+     *
+     * Returns counts of all major entity types stored in the database.
+     * Used for displaying indexing results and system health checks.
+     *
+     * @returns Object containing counts for:
+     * - `conversations`: Total conversations indexed
+     * - `messages`: Total messages stored
+     * - `decisions`: Total decisions extracted
+     * - `mistakes`: Total mistakes documented
+     * - `git_commits`: Total git commits linked
+     *
+     * @example
+     * ```typescript
+     * const stats = storage.getStats();
+     * console.error(`Indexed ${stats.conversations.count} conversations`);
+     * console.error(`Extracted ${stats.decisions.count} decisions`);
+     * console.error(`Linked ${stats.git_commits.count} commits`);
+     * ```
+     */
+    getStats() {
+        const stats = {
+            conversations: this.db
+                .prepare("SELECT COUNT(*) as count FROM conversations")
+                .get(),
+            messages: this.db
+                .prepare("SELECT COUNT(*) as count FROM messages")
+                .get(),
+            decisions: this.db
+                .prepare("SELECT COUNT(*) as count FROM decisions")
+                .get(),
+            mistakes: this.db
+                .prepare("SELECT COUNT(*) as count FROM mistakes")
+                .get(),
+            git_commits: this.db
+                .prepare("SELECT COUNT(*) as count FROM git_commits")
+                .get(),
+        };
+        return stats;
+    }
+}
+//# sourceMappingURL=ConversationStorage.js.map