Claude Historian

Instructions

Implementation Reference

• src/index.ts:181-205 (registration)

  Registration and input schema definition for the 'extract_compact_summary' tool in the MCP ListTools response.

  {
    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'],
    },
  },

• src/index.ts:355-373 (handler)

  MCP CallToolRequestSchema handler case for 'extract_compact_summary': delegates to UniversalHistorySearchEngine.generateCompactSummary and formats output using BeautifulFormatter.formatCompactSummary.

  case 'extract_compact_summary': {
    const sessionId = args?.session_id as string;
    const maxMessages = (args?.max_messages as number) || 10;
    const focus = (args?.focus as string) || 'all';
  
    const universalResult = await this.universalEngine.generateCompactSummary(
      sessionId,
      maxMessages,
      focus
    );
    const formattedResult = this.formatter.formatCompactSummary(
      [universalResult.results as any],
      sessionId
    );
  
    return {
      content: [{ type: 'text', text: formattedResult }],
    };
  }

• src/universal-engine.ts:1448-1535 (handler)

  Core implementation of compact summary generation: resolves session ID, fetches messages via HistorySearchEngine.getSessionMessages, extracts tools/files/accomplishments/decisions, returns structured summary data.

  async generateCompactSummary(
    sessionId: string,
    maxMessages?: number,
    focus?: string
  ): Promise<UniversalSearchResult> {
    await this.initialize();
  
    // Get session data from Claude Code
    const allSessions = await this.claudeCodeEngine.getRecentSessions(20);
  
    // Support "latest" keyword - resolve to most recent session
    let resolvedSessionId = sessionId;
    if (sessionId.toLowerCase() === 'latest') {
      if (allSessions.length > 0) {
        resolvedSessionId = allSessions[0].session_id;
      } else {
        return {
          source: 'claude-code',
          results: {
            session_id: 'latest',
            end_time: null,
            start_time: null,
            duration_minutes: 0,
            message_count: 0,
            project_path: null,
            tools_used: [],
            files_modified: [],
            accomplishments: [],
            key_decisions: [],
          } as any,
          enhanced: false,
        };
      }
    }
  
    const sessionData = allSessions.find(
      (s) =>
        s.session_id === resolvedSessionId ||
        s.session_id.startsWith(resolvedSessionId) ||
        resolvedSessionId.includes(s.session_id) ||
        s.session_id.includes(resolvedSessionId.replace(/^.*\//, ''))
    );
  
    if (!sessionData) {
      return {
        source: 'claude-code',
        results: {
          session_id: resolvedSessionId,
          end_time: null,
          start_time: null,
          duration_minutes: 0,
          message_count: 0,
          project_path: null,
          tools_used: [],
          files_modified: [],
          accomplishments: [],
          key_decisions: [],
        } as any,
        enhanced: false,
      };
    }
  
    const messages = await this.claudeCodeEngine.getSessionMessages(
      sessionData.project_dir,
      sessionData.session_id
    );
    const sessionMessages = messages.slice(0, maxMessages || 100); // Increased from 50 to 100 for better extraction
  
    // Return rich session object with extracted content
    const richSummary = {
      session_id: sessionData.session_id,
      end_time: sessionData.end_time,
      start_time: sessionData.start_time,
      duration_minutes: sessionData.duration_minutes || 0,
      message_count: sessionMessages.length,
      project_path: sessionData.project_path,
      tools_used: this.extractToolsFromMessages(sessionMessages),
      files_modified: this.extractFilesFromMessages(sessionMessages),
      accomplishments: this.extractAccomplishmentsFromMessages(sessionMessages),
      key_decisions: this.extractDecisionsFromMessages(sessionMessages),
    };
  
    return {
      source: 'claude-code',
      results: richSummary as any,
      enhanced: this.claudeDesktopAvailable === true,
    };
  }

• src/formatter.ts:814-840 (helper)

  Helper function to format the compact summary data into a readable string with robot emoji header and structured JSON containing session metrics, tools, files, accomplishments, and decisions.

  formatCompactSummary(sessions: any[], sessionId?: string): string {
    if (sessions.length === 0) {
      const filter = sessionId ? `"${sessionId}"` : 'latest';
      return `${robots.summary} ${filter}\n\n{"session":null}`;
    }
  
    const s = sessions[0];
    // Create a useful header with project name and session info
    const projectName = s.project_path?.split('/').pop() || 'unknown';
    const shortId = s.session_id?.substring(0, 8) || sessionId?.substring(0, 8) || 'latest';
    const header = `${robots.summary} extracting summary from ${projectName} (${shortId})`;
    const structured = {
      session: {
        id: s.session_id?.substring(0, 8) || null,
        ts: this.formatTimestamp(s.end_time || s.start_time),
        duration: s.duration_minutes || 0,
        messages: s.message_count || 0,
        project: s.project_path?.split('/').pop() || null,
        tools: s.tools_used || null,
        files: s.files_modified || null,
        accomplishments: s.accomplishments || null,
        decisions: s.key_decisions || null,
      },
    };
  
    return `${header}\n\n${JSON.stringify(structured, null, 2)}`;
  }