How Apache Maka Summarizes Long Conversations: A Complete Technical Guide

Apache Maka can summarize long conversations by storing exchanges as session-based messages and generating deterministic markdown summaries that are persisted in session headers for cheap downstream access.

This deep dive examines how the apache/maka repository implements conversation summarization without external API calls, using a pipeline that transforms raw turn-by-turn chat data into compact, queryable summaries.

How Maka Structures Conversations for Summarization

Session-Based Message Storage

Every user-assistant exchange in Maka is stored as a message inside a session record. The SessionHeader interface in packages/storage/src/session-store.ts defines the core data structure:

interface SessionHeader {
  id: string;
  messages: Message[];
  summary?: string;  // Optional summary field for condensed conversation data
  // ... other metadata
}

The optional summary field holds the pre-computed conversation summary, making it available without re-reading the full message history. This design choice enables O(1) summary retrieval regardless of conversation length.

When Summarization Triggers

Maka initiates summarization through two mechanisms:

• Automatic: When a session exceeds configurable message count or token thresholds
• Explicit: Via user request or CLI command (maka session summarize --id <sessionId>)

The Four-Stage Summarization Pipeline

Stage 1: Turn Collection

The storage layer aggregates messages from the active session. Each turn contains role (user/assistant), content, and timestamp data preserved in the SessionHeader structure.

Stage 2: Summary Generation via conversation-copy.ts

The core summarization logic resides in packages/ui/src/conversation-copy.ts. This module orchestrates the transformation from raw messages to markdown:

// From packages/ui/src/conversation-copy.ts
export function getConversationCopy(session: Session): ConversationCopy {
  const summary = buildSummary(session.messages);
  return {
    markdown: formatAsMarkdown(summary),
    stats: computeTokenStats(session)
  };
}

Key characteristics of this stage:

• Deterministic output: No LLM hallucination—summaries are constructed from actual message data
• Markdown styling: Uses headings, bullet points, and collapsible sections
• Statistics inclusion: Token counts, message totals, and duration metrics

Stage 3: Persisting the Summary

The generated markdown is written back to the session header via SessionStore.updateHeader():

// From packages/storage/src/session-store.ts
async updateHeader(sessionId: string, updates: Partial<SessionHeader>) {
  const header = await this.readHeader(sessionId);
  const updated = { ...header, ...updates };
  await this.writeHeader(sessionId, updated);
}

This persistence model ensures subsequent tool calls can use the summary as a cheap context source, dramatically reducing prompt length for long conversations.

Stage 4: UI Presentation and Interaction

Two files handle summary display in the Maka interface:

• packages/ui/src/tool-activity/result-projection.ts — Renders the summary chip with collapsible <details>/<summary> HTML elements
• packages/ui/src/tool-activity/copy.ts — Provides copy-to-clipboard functionality

Daily Review Aggregation

Maka extends single-session summaries into daily review documents through packages/ui/src/daily-review-helpers.ts:

// From packages/ui/src/daily-review-helpers.ts
export function buildDailyReview(sessions: Session[]): string {
  const sections = sessions.map(s => ({
    heading: `Session ${s.id} (${s.messageCount} messages)`,
    summary: s.summary || 'No summary available',
    tokenUsage: s.tokenCount
  }));
  
  return sections.map(renderMarkdownSection).join('\n\n');
}

This nightly aggregation produces exportable markdown documents suitable for external note-taking systems.

Practical Implementation Examples

Retrieving a Stored Summary via Node SDK

import { MakaClient } from '@apache/maka-client';

const client = new MakaClient();
const sessionId = 'abc123';

// Fetch pre-computed summary from session header
const summary = await client.session.getSummary(sessionId);

console.log(summary);
// Output: Markdown summary with conversation overview and statistics

The SDK's getSummary method reads directly from SessionHeader.summary, bypassing message reconstruction.

Triggering Fresh Summarization from CLI

# Force regeneration for a large session

maka session summarize --id abc123 --force

# Output includes:

# - New summary markdown

# - Token savings vs. full conversation

# - Timestamp of generation

This CLI command invokes the same conversation-copy.ts pipeline used by the automatic trigger.

Using Summaries as Compressed Context

import { MakaClient } from '@apache/maka-client';

const client = new MakaClient();
const sessionId = 'abc123';

const summary = await client.session.getSummary(sessionId);

// Pass summary instead of full message history
await client.chat.send({
  sessionId: 'new-continuation-session',
  systemPrompt: `Prior context: ${summary}`,
  userPrompt: 'Continue the analysis from where we left off...'
});

This pattern preserves conversation intent while staying within model token limits—critical for sessions exceeding context windows.

Key Implementation Files

File	Purpose
packages/storage/src/session-store.ts	Defines SessionHeader with summary field; persistence operations
packages/ui/src/conversation-copy.ts	Core summarization orchestration and markdown generation
packages/ui/src/daily-review-helpers.ts	Multi-session aggregation for daily exports
packages/ui/src/tool-activity/result-projection.ts	UI rendering of summary components
packages/storage/src/usage-stores.ts	Exposes summary(query) API for external consumers

Summary

• Apache Maka summarizes long conversations through a deterministic, storage-integrated pipeline requiring no external services
• Session headers store pre-computed markdown summaries, enabling O(1) retrieval regardless of conversation length
• packages/ui/src/conversation-copy.ts implements the core transformation from message array to structured summary
• Summaries serve as cheap context sources for downstream operations, solving token limit constraints
• Daily review aggregation extends single-session summaries into multi-session reports via daily-review-helpers.ts

Frequently Asked Questions

Does Apache Maka use an LLM to generate conversation summaries?

No. According to the apache/maka source code, summaries are deterministically constructed from actual message data in conversation-copy.ts, not generated by language model inference. This eliminates hallucination risk and removes dependency on external API availability.

How much storage does a summary save compared to full conversation history?

The summary field stores condensed markdown—typically 10-20 lines—versus potentially hundreds of raw message objects. For a 100-message session, this commonly represents 90%+ reduction in storage size and corresponding prompt token reduction when used as context.

Can summaries be accessed programmatically outside the Maka UI?

Yes. The usage-stores.ts module exposes a summary(query) API, and the Node SDK provides client.session.getSummary(sessionId). Both interfaces read directly from the persisted SessionHeader.summary field without reconstructing message history.

What triggers automatic summarization in long-running sessions?

The storage layer monitors message count and cumulative token totals against configurable thresholds. When exceeded, the session is flagged for summarization, which executes through the same conversation-copy.ts pipeline used for explicit requests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}