claude-conversation-memory-mcp 0.5.0 → 1.0.0

package/dist/storage/ConversationStorage.d.ts

@@ -1,6 +1,20 @@
 /**
- * Conversation Storage Layer
- * CRUD operations for all conversation-related data
+ * Conversation Storage Layer - CRUD operations for all conversation-related data.
+ *
+ * This class provides the data access layer for the conversation-memory 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 type { SQLiteManager } from "./SQLiteManager.js";
 import type { Conversation, Message, ToolUse, ToolResult, FileEdit, ThinkingBlock } from "../parsers/ConversationParser.js";
@@ -8,30 +22,285 @@ import type { Decision } from "../parsers/DecisionExtractor.js";
 import type { Mistake } from "../parsers/MistakeExtractor.js";
 import type { GitCommit } from "../parsers/GitIntegrator.js";
 import type { Requirement, Validation } from "../parsers/RequirementsExtractor.js";
+import { type QueryCacheConfig, type CacheStats } from "../cache/QueryCache.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 declare class ConversationStorage {
     private db;
+    private cache;
+    /**
+     * Create a new ConversationStorage instance.
+     *
+     * @param db - SQLiteManager instance for database access
+     */
     constructor(db: SQLiteManager);
+    /**
+     * 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: QueryCacheConfig): void;
+    /**
+     * Disable query result caching.
+     *
+     * Clears all cached data and stops caching new queries.
+     */
+    disableCache(): void;
+    /**
+     * Check if caching is enabled.
+     *
+     * @returns True if caching is enabled
+     */
+    isCacheEnabled(): boolean;
+    /**
+     * Clear all cached query results.
+     *
+     * Clears the cache but keeps caching enabled.
+     */
+    clearCache(): void;
+    /**
+     * 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.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+     * }
+     * ```
+     */
+    getCacheStats(): CacheStats | null;
+    /**
+     * Store conversations in the database.
+     *
+     * Uses INSERT OR REPLACE 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()
+     *   }
+     * ]);
+     * ```
+     */
     storeConversations(conversations: Conversation[]): Promise<void>;
+    /**
+     * 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.log(`${conv.message_count} messages on ${conv.git_branch}`);
+     * }
+     * ```
+     */
     getConversation(id: string): Conversation | null;
+    /**
+     * Store messages in the database.
+     *
+     * Stores all messages from conversations including content, metadata, and relationships.
+     * Uses INSERT OR REPLACE for idempotent storage.
+     *
+     * @param messages - Array of message objects to store
+     * @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: {}
+     *   }
+     * ]);
+     * ```
+     */
     storeMessages(messages: Message[]): Promise<void>;
+    /**
+     * 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
+     */
     storeToolUses(toolUses: ToolUse[]): Promise<void>;
+    /**
+     * 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
+     */
     storeToolResults(toolResults: ToolResult[]): Promise<void>;
+    /**
+     * 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
+     */
     storeFileEdits(fileEdits: FileEdit[]): Promise<void>;
+    /**
+     * 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: string): FileEdit[];
+    /**
+     * 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
+     */
     storeThinkingBlocks(blocks: ThinkingBlock[]): Promise<void>;
+    /**
+     * Store extracted decisions in the database.
+     *
+     * Decisions include architectural choices, technical decisions, and their rationale.
+     *
+     * @param decisions - Array of decision objects
+     * @returns Promise that resolves when stored
+     */
     storeDecisions(decisions: Decision[]): Promise<void>;
+    /**
+     * 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: string): Decision[];
+    /**
+     * 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
+     */
     storeGitCommits(commits: GitCommit[]): Promise<void>;
     getCommitsForFile(filePath: string): GitCommit[];
+    /**
+     * 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
+     */
     storeMistakes(mistakes: Mistake[]): Promise<void>;
+    /**
+     * 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
+     */
     storeRequirements(requirements: Requirement[]): Promise<void>;
+    /**
+     * 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
+     */
     storeValidations(validations: Validation[]): Promise<void>;
+    /**
+     * 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.log(`${timeline.edits.length} edits`);
+     * console.log(`${timeline.commits.length} commits`);
+     * console.log(`${timeline.decisions.length} decisions`);
+     * ```
+     */
     getFileTimeline(filePath: string): {
         file_path: string;
         edits: FileEdit[];
         commits: GitCommit[];
         decisions: Decision[];
     };
+    /**
+     * 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.log(`Indexed ${stats.conversations.count} conversations`);
+     * console.log(`Extracted ${stats.decisions.count} decisions`);
+     * console.log(`Linked ${stats.git_commits.count} commits`);
+     * ```
+     */
     getStats(): {
         conversations: {
             count: number;

package/dist/storage/ConversationStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConversationStorage.d.ts","sourceRoot":"","sources":["../../src/storage/ConversationStorage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EACP,OAAO,EACP,UAAU,EACV,QAAQ,EACR,aAAa,EACd,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAInF,qBAAa,mBAAmB;IAClB,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,aAAa;IAI/B,kBAAkB,CAAC,aAAa,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BtE,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAiB1C,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCjD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBjD,gBAAgB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B1D,cAAc,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B1D,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE;IAUpC,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB3D,cAAc,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B1D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE;IAiB3C,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B1D,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE;IAe1C,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BjD,iBAAiB,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B7D,gBAAgB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BhE,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG;QACjC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;QAClB,OAAO,EAAE,SAAS,EAAE,CAAC;QACrB,SAAS,EAAE,QAAQ,EAAE,CAAC;KACvB;IAcD,QAAQ,IAAI;QACV,aAAa,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QACjC,QAAQ,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5B,SAAS,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7B,QAAQ,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5B,WAAW,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC;CAqBF"}
+{"version":3,"file":"ConversationStorage.d.ts","sourceRoot":"","sources":["../../src/storage/ConversationStorage.ts"],"names":[],"mappings":"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"}