# How Apache Maka Summarizes Long Conversations: A Complete Technical Guide

> Learn how Apache Maka summarizes long conversations using session-based messages and deterministic markdown summaries for efficient downstream access. Explore this technical guide.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-29

---

**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`](https://github.com/apache/maka/blob/main/packages/storage/src/session-store.ts) defines the core data structure:

```typescript
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`](https://github.com/apache/maka/blob/main/conversation-copy.ts)

The core summarization logic resides in [`packages/ui/src/conversation-copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/conversation-copy.ts). This module orchestrates the transformation from raw messages to markdown:

```typescript
// 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()`:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/ui/src/daily-review-helpers.ts):

```typescript
// 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

```typescript
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

```bash

# 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`](https://github.com/apache/maka/blob/main/conversation-copy.ts) pipeline used by the automatic trigger.

### Using Summaries as Compressed Context

```typescript
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`](https://github.com/apache/maka/blob/main/packages/storage/src/session-store.ts) | Defines `SessionHeader` with `summary` field; persistence operations |
| [`packages/ui/src/conversation-copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/conversation-copy.ts) | Core summarization orchestration and markdown generation |
| [`packages/ui/src/daily-review-helpers.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/daily-review-helpers.ts) | Multi-session aggregation for daily exports |
| [`packages/ui/src/tool-activity/result-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/result-projection.ts) | UI rendering of summary components |
| [`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/conversation-copy.ts) pipeline used for explicit requests.