Claude Historian

Instructions

Implementation Reference

• src/index.ts:284-302 (handler)

  MCP server dispatch handler for 'find_file_context' tool: extracts args, calls UniversalHistorySearchEngine.findFileContext, formats result with BeautifulFormatter
  case 'find_file_context': { const universalResult = await this.universalEngine.findFileContext( args?.filepath as string, (args?.limit as number) || 15 ); const detailLevel = (args?.detail_level as string) || 'summary'; const operationType = (args?.operation_type as string) || 'all'; const formattedResult = this.formatter.formatFileContext( universalResult.results, args?.filepath as string, detailLevel, operationType ); return { content: [{ type: 'text', text: formattedResult }], }; }
• src/universal-engine.ts:1117-1144 (handler)

  UniversalHistorySearchEngine.findFileContext: proxies to HistorySearchEngine.findFileContext (primary impl), adds desktop support (currently disabled)
  async findFileContext( filepath: string, limit?: number ): Promise<{ source: string; results: FileContext[]; enhanced: boolean }> { await this.initialize(); const claudeCodeResults = await this.claudeCodeEngine.findFileContext(filepath, limit); if (!this.claudeDesktopAvailable) { return { source: 'claude-code', results: claudeCodeResults, enhanced: false, }; } const desktopMessages = await this.searchClaudeDesktopConversations(filepath, undefined, limit); const combinedResults = this.combineFileContextResults(claudeCodeResults, desktopMessages); const hasDesktopData = desktopMessages.length > 0; return { source: hasDesktopData ? 'claude-desktop' : 'claude-code', results: combinedResults, enhanced: hasDesktopData, }; }
• src/search.ts:735-851 (handler)

  Core HistorySearchEngine.findFileContext implementation: parallel search across projects' jsonl conversation files for messages referencing the filepath, extracts related contexts grouped by operation
  async findFileContext(filePath: string, limit: number = 25): Promise<FileContext[]> { const fileContexts: FileContext[] = []; try { const projectDirs = await findProjectDirectories(); // COMPREHENSIVE: Process more projects to match GLOBAL's reach const limitedDirs = projectDirs.slice(0, 15); // Increased significantly to match GLOBAL scope // PARALLEL PROCESSING: Process all projects concurrently const projectResults = await Promise.allSettled( limitedDirs.map(async (projectDir) => { const jsonlFiles = await findJsonlFiles(projectDir); // COMPREHENSIVE: Process more files to match GLOBAL's reach const limitedFiles = jsonlFiles.slice(0, 10); // Increased to match GLOBAL scope const fileResults = await Promise.allSettled( limitedFiles.map(async (file) => { const messages = await this.parser.parseJsonlFile(projectDir, file); const fileMessages = messages.filter((msg) => { // ENHANCED file matching logic like GLOBAL with more patterns const hasFileRef = msg.context?.filesReferenced?.some((ref) => { const refLower = ref.toLowerCase(); const pathLower = filePath.toLowerCase(); // More comprehensive matching patterns return ( refLower.includes(pathLower) || pathLower.includes(refLower) || refLower.endsWith('/' + pathLower) || pathLower.endsWith('/' + refLower) || refLower.split('/').pop() === pathLower || pathLower.split('/').pop() === refLower || refLower === pathLower || refLower.includes(pathLower.replace(/\\/g, '/')) || refLower.includes(pathLower.replace(/\//g, '\\')) ); }); // Enhanced content matching with case variations and path separators const contentLower = msg.content.toLowerCase(); const pathVariations = [ filePath.toLowerCase(), filePath.toLowerCase().replace(/\\/g, '/'), filePath.toLowerCase().replace(/\//g, '\\'), filePath.toLowerCase().split('/').pop() || '', filePath.toLowerCase().split('\\').pop() || '', ]; const hasContentRef = pathVariations.some( (variation) => variation.length > 0 && contentLower.includes(variation) ); // Enhanced git pattern matching const hasGitRef = /(?:modified|added|deleted|new file|renamed|M\s+|A\s+|D\s+)[\s:]*[^\n]*/.test( msg.content ) && pathVariations.some( (variation) => variation.length > 0 && contentLower.includes(variation) ); return hasFileRef || hasContentRef || hasGitRef; }); if (fileMessages.length > 0) { // Claude-optimized filtering - preserve valuable context const cleanFileMessages = fileMessages.filter((msg) => { return msg.content.length > 15 && !this.isLowValueContent(msg.content); }); const dedupedMessages = SearchHelpers.deduplicateByContent(cleanFileMessages); if (dedupedMessages.length > 0) { // Group by operation type (heuristic) const operationType = SearchHelpers.inferOperationType(dedupedMessages); return { filePath, lastModified: dedupedMessages[0]?.timestamp || '', relatedMessages: dedupedMessages.slice(0, Math.min(limit, 10)), // More context for Claude operationType, }; } } return null; }) ); // Collect successful file results const validContexts: FileContext[] = []; for (const result of fileResults) { if (result.status === 'fulfilled' && result.value) { validContexts.push(result.value); } } return validContexts; }) ); // Aggregate all results from parallel processing for (const result of projectResults) { if (result.status === 'fulfilled') { fileContexts.push(...result.value); } } return fileContexts.sort( (a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime() ); } catch (error) { console.error('File context search error:', error); return []; } }
• src/index.ts:77-107 (schema)

  Input schema and metadata definition for find_file_context tool in MCP ListTools response
  { name: 'find_file_context', description: 'Find all conversations and changes related to a specific file', inputSchema: { type: 'object', properties: { filepath: { type: 'string', description: 'File path to search for in conversation history', }, operation_type: { type: 'string', description: 'Filter by operation: read, edit, create, or all', enum: ['read', 'edit', 'create', 'all'], default: 'all', }, limit: { type: 'number', description: 'Maximum number of results (default: 15)', default: 15, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['filepath'], }, },
• src/index.ts:41-256 (registration)

  Registration of all tools including find_file_context in MCP ListToolsRequestSchema handler
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'search_conversations', description: 'Search through Claude Code conversation history with smart insights', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query to find relevant conversations', }, project: { type: 'string', description: 'Optional project name to filter results', }, timeframe: { type: 'string', description: 'Time range filter (today, week, month)', }, limit: { type: 'number', description: 'Maximum number of results (default: 10)', default: 10, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['query'], }, }, { name: 'find_file_context', description: 'Find all conversations and changes related to a specific file', inputSchema: { type: 'object', properties: { filepath: { type: 'string', description: 'File path to search for in conversation history', }, operation_type: { type: 'string', description: 'Filter by operation: read, edit, create, or all', enum: ['read', 'edit', 'create', 'all'], default: 'all', }, limit: { type: 'number', description: 'Maximum number of results (default: 15)', default: 15, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['filepath'], }, }, { name: 'find_similar_queries', description: 'Find previous similar questions or queries with enhanced matching', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Query to find similar previous questions', }, limit: { type: 'number', description: 'Maximum number of results (default: 8)', default: 8, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['query'], }, }, { name: 'get_error_solutions', description: 'Find solutions for specific errors with enhanced matching', inputSchema: { type: 'object', properties: { error_pattern: { type: 'string', description: 'Error message or pattern to search for solutions', }, limit: { type: 'number', description: 'Maximum number of results (default: 8)', default: 8, }, detail_level: { type: 'string', description: 'Response detail: summary (default), detailed, raw', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['error_pattern'], }, }, { name: 'list_recent_sessions', description: 'Browse recent sessions with smart activity detection and summaries', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of sessions (default: 10)', default: 10, }, project: { type: 'string', description: 'Optional project name to filter sessions', }, include_summary: { type: 'boolean', description: 'Include intelligent session summaries (default: true)', default: true, }, }, }, }, { name: 'extract_compact_summary', description: 'Get intelligent summary of a conversation session with key insights', inputSchema: { type: 'object', properties: { session_id: { type: 'string', description: 'Session ID to summarize', }, max_messages: { type: 'number', description: 'Maximum messages to analyze (default: 10)', default: 10, }, focus: { type: 'string', description: 'Focus area: solutions, tools, files, or all', enum: ['solutions', 'tools', 'files', 'all'], default: 'all', }, }, required: ['session_id'], }, }, { name: 'find_tool_patterns', description: 'Analyze tool usage patterns, workflows, and successful practices', inputSchema: { type: 'object', properties: { tool_name: { type: 'string', description: 'Optional specific tool name to analyze', }, pattern_type: { type: 'string', description: 'Type of patterns: tools, workflows, or solutions', enum: ['tools', 'workflows', 'solutions'], default: 'tools', }, limit: { type: 'number', description: 'Maximum number of patterns (default: 12)', default: 12, }, }, }, }, { name: 'search_plans', description: 'Search Claude Code plan files for past implementation approaches, decisions, and patterns', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query for plan content', }, limit: { type: 'number', description: 'Maximum number of results (default: 10)', default: 10, }, detail_level: { type: 'string', description: 'Response detail level', enum: ['summary', 'detailed', 'raw'], default: 'summary', }, }, required: ['query'], }, }, ],