Claude Historian

Instructions

Implementation Reference

• src/index.ts:304-320 (handler)

  MCP tool handler for 'find_similar_queries': extracts parameters, calls UniversalHistorySearchEngine.findSimilarQueries, formats result with BeautifulFormatter.formatSimilarQueries based on detail_level, and returns formatted text content.
  case 'find_similar_queries': { const universalResult = await this.universalEngine.findSimilarQueries( args?.query as string, (args?.limit as number) || 8 ); const detailLevel = (args?.detail_level as string) || 'summary'; const formattedResult = this.formatter.formatSimilarQueries( universalResult.results, args?.query as string, detailLevel ); return { content: [{ type: 'text', text: formattedResult }], }; }
• src/index.ts:109-131 (schema)

  Input schema definition for the 'find_similar_queries' tool, including required 'query' string, optional 'limit' number (default 8), and 'detail_level' enum (summary/detailed/raw, default summary). Returned in tools/list response.
  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'], },
• src/search.ts:853-923 (handler)

  Core implementation of findSimilarQueries in HistorySearchEngine: scans conversation JSONL files across projects for user queries similar to targetQuery (using SearchHelpers.calculateQuerySimilarity >0.4 threshold), attaches following assistant response as claudeInsights, filters low-value content, sorts by relevance, limits to requested number.
  async findSimilarQueries(targetQuery: string, limit: number = 10): Promise<CompactMessage[]> { const allMessages: CompactMessage[] = []; try { const projectDirs = await findProjectDirectories(); // BALANCED: More projects for better coverage, early termination for speed const limitedDirs = projectDirs.slice(0, 8); for (const projectDir of limitedDirs) { const jsonlFiles = await findJsonlFiles(projectDir); // BALANCED: More files per project for better context const limitedFiles = jsonlFiles.slice(0, 5); for (const file of limitedFiles) { const messages = await this.parser.parseJsonlFile(projectDir, file); // Find user messages (queries) that are similar and valuable const userQueries = messages.filter( (msg) => msg.type === 'user' && msg.content.length > 15 && msg.content.length < 800 && !this.isLowValueContent(msg.content) // Only quality queries ); for (let i = 0; i < userQueries.length; i++) { const query = userQueries[i]; const similarity = SearchHelpers.calculateQuerySimilarity(targetQuery, query.content); // Raised threshold to 0.4 and REMOVED partial keyword fallback (causes false positives) if (similarity > 0.4) { query.relevanceScore = similarity; // Find the answer - look for next assistant message in original array const queryIndex = messages.findIndex((m) => m.uuid === query.uuid); if (queryIndex >= 0) { // Look ahead for assistant response (may not be immediately next) for (let j = queryIndex + 1; j < Math.min(queryIndex + 5, messages.length); j++) { const nextMsg = messages[j]; if (nextMsg.type === 'assistant' && nextMsg.content.length > 50) { query.context = query.context || {}; query.context.claudeInsights = [nextMsg.content.substring(0, 400)]; break; } } } allMessages.push(query); } } // SPEED FIX: Early termination when we have enough candidates if (allMessages.length >= limit * 4) break; } if (allMessages.length >= limit * 4) break; } // Quality filter and return only if we have valuable results const qualityResults = allMessages .filter((msg) => !this.isLowValueContent(msg.content)) .sort((a, b) => (b.relevanceScore || 0) - (a.relevanceScore || 0)) .slice(0, limit); return qualityResults; } catch (error) { console.error('Similar query search error:', error); return []; } }
• src/universal-engine.ts:1160-1187 (helper)

  UniversalHistorySearchEngine.findSimilarQueries: delegates to HistorySearchEngine.findSimilarQueries (claudeCodeEngine), optionally combines with Claude Desktop search results (disabled), returns source, results, enhanced flag.
  async findSimilarQueries( query: string, limit?: number ): Promise<{ source: string; results: CompactMessage[]; enhanced: boolean }> { await this.initialize(); const claudeCodeResults = await this.claudeCodeEngine.findSimilarQueries(query, limit); if (!this.claudeDesktopAvailable) { return { source: 'claude-code', results: claudeCodeResults, enhanced: false, }; } const desktopMessages = await this.searchClaudeDesktopConversations(query, undefined, limit); const combinedResults = [...claudeCodeResults, ...desktopMessages]; const hasDesktopData = desktopMessages.length > 0; return { source: hasDesktopData ? 'claude-desktop' : 'claude-code', results: combinedResults, enhanced: hasDesktopData, }; }
• src/index.ts:41-256 (registration)

  Tool registration in MCP ListToolsRequestSchema handler: includes 'find_similar_queries' in the tools array with name, description, inputSchema.
  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'], }, }, ],