# How Maka Handles Context Compaction and History Pruning: A Two-Step Projection System

> Learn how Maka reduces LLM context with a two-step projection system. Discover its deterministic approach to context compaction and history pruning for replayability and auditability.

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

---

**Maka reduces LLM context usage through a deterministic two-step process—selecting a safe prefix of immutable events and building a durable checkpoint—while preserving replayability and auditability.**

Maka implements **context compaction** and **history pruning** to keep conversation history within provider token limits without sacrificing the ability to reconstruct, audit, or replay sessions. This article examines the runtime mechanisms, source file locations, and practical usage patterns based on the actual implementation in `apache/maka`.

## The Two-Step Compaction Architecture

Maka's compaction system operates as a **projection layer** over an immutable ledger of `RuntimeEvent` records. Rather than mutating history, it creates a checkpoint that summarizes a safe prefix of events, then projects future requests from that checkpoint plus remaining uncovered events.

### Step 1: Selecting a Safe Compaction Prefix

The `selectSafeCompactionPrefix` function in **[[`packages/runtime/src/history-compaction.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compaction.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compaction.ts)** scans the event ledger to identify the largest contiguous prefix that can be safely summarized.

This function enforces **structural safety invariants**:

- **No split streaming snapshots** — partial snapshots are excluded from the prefix
- **No split pinned events** — pinned messages remain intact
- **No orphaned tool calls** — the `toolPairSpans` helper ensures tool-call/result pairs are never separated

The algorithm preserves a **configurable tail of uncovered events** to maintain conversational continuity. This deterministic selection guarantees that the remaining ledger remains **immutable and replayable** even after compaction.

### Step 2: Building a Compact Checkpoint

Once a safe prefix is selected, `buildHistoryCompactCheckpoint` in **[[`packages/runtime/src/history-compact-checkpoint.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compact-checkpoint.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compact-checkpoint.ts)** constructs a durable checkpoint containing:

- Coverage bounds of the selected prefix
- A source digest for integrity verification
- **V2**: a text summary generated by a summarizer model
- **V3**: provider-native state (for compatible LLM providers)

The checkpoint is stored as an `AgentRun` event and referenced by future turns through the `ContextCompactionOutcome` type defined in **[[`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts)](https://github.com/apache/maka/blob/main/packages/core/src/events.ts)**.

## Automatic Triggering and Token Estimation

Compaction occurs automatically when the runtime detects an impending context overflow. The `estimateNextRequestTokens` function predicts token usage for the upcoming provider call. If this exceeds the model's configured high-water mark (`exceedsHighWater`), compaction is triggered before the request is built.

```typescript
import { RuntimeKernel } from '@maka/runtime';

// Compaction happens automatically during normal operation
// when token estimates exceed thresholds
await kernel.processTurn({
  sessionId: 'my-session-id',
  messages: newMessages,
  // The runtime internally calls:
  // 1. estimateNextRequestTokens()
  // 2. selectSafeCompactionPrefix() if needed
  // 3. buildHistoryCompactCheckpoint() to create projection
});

```

## Fail-Open Behavior and Context Budget Exhaustion

Maka implements **defensive degradation** when compaction cannot produce a valid result. If the summarizer returns empty output, or if the input still exceeds budget after prefix selection, the system follows a **fail-open path**:

- The turn is marked with `context_compaction_failed_open`
- The original, uncompacted history is sent to the provider
- The session ends with `context_budget_exhausted`

This behavior ensures that user requests are not silently dropped, while clearly signaling that the conversation has reached architectural limits.

## History Pruning Through Deterministic Omission

**History pruning** uses the same safe-prefix algorithm as compaction. When tool-call/result pairs exceed the available context budget, Maka may:

- Omit older tool-result payloads
- Replace them with a **fixed omission marker**
- Preserve the call/response relationship for audit purposes

This approach maintains ledger integrity without requiring speculative edits. The pruned events remain reconstructible from earlier checkpoints in the event stream.

## Practical Usage Examples

### Manual Session Compaction (Desktop Command)

Trigger compaction explicitly using the `sessions:compact` command:

```typescript
import { RuntimeKernel } from '@maka/runtime';

await kernel.compactSession({
  sessionId: 'my-session-id',
  // Optional: force a specific checkpoint ID
  // checkpointId: 'checkpoint-123',
});

```

This creates a new Turn/Run, executes the two-step compaction process, and attaches the outcome to `ContextCompactionOutcome`.

### Inspecting Compaction Outcomes

Examine compaction results from completed turns:

```typescript
import { readTurn } from '@maka/runtime-host';

const turn = await readTurn('session-42', 'turn-7');
if (turn.contextCompactionOutcome) {
  console.log('Compaction result:', turn.contextCompactionOutcome);
  // Possible values:
  // { kind: 'compacted', checkpointId: string }
  // { kind: 'failed', reason: 'context_budget_exhausted' }
}

```

The `TurnSnapshot` type in **[[`packages/runtime-host/src/protocol/turn.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/turn.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/turn.ts)** defines this structure.

### Rendering Compaction Notices in the UI

Display user-friendly compaction events:

```tsx
import { contextCompactionNotice } from '@maka/desktop/app-shell-context-compaction';

function onCompaction(outcome: ContextCompactionOutcome) {
  const notice = contextCompactionNotice(outcome, uiLocale);
  presentTerminal(sessionId, notice);
}

```

The helper in **[[`apps/desktop/src/renderer/app-shell-context-compaction.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/app-shell-context-compaction.ts)](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/app-shell-context-compaction.ts)** formats outcomes for terminal presentation.

## Key Source Files and Architecture References

| File | Purpose | Location |
|------|---------|----------|
| [`history-compaction.ts`](https://github.com/apache/maka/blob/main/history-compaction.ts) | Safe-prefix selection, token estimation, high-water checks | [`packages/runtime/src/history-compaction.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compaction.ts) |
| [`history-compact-checkpoint.ts`](https://github.com/apache/maka/blob/main/history-compact-checkpoint.ts) | Checkpoint construction, validation, serialization (V2/V3) | [`packages/runtime/src/history-compact-checkpoint.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/history-compact-checkpoint.ts) |
| [`events.ts`](https://github.com/apache/maka/blob/main/events.ts) | `ContextCompactionOutcome` type definition | [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) |
| [`turn.ts`](https://github.com/apache/maka/blob/main/turn.ts) | Turn snapshot protocol including compaction outcomes | [`packages/runtime-host/src/protocol/turn.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/turn.ts) |
| [`app-shell-context-compaction.tsx`](https://github.com/apache/maka/blob/main/app-shell-context-compaction.tsx) | UI notice rendering for compaction events | [`apps/desktop/src/renderer/app-shell-context-compaction.ts`](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/app-shell-context-compaction.ts) |
| [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) | High-level compaction node in backend architecture | Repository root |
| [`llm-compaction-events-log-projection-draft.md`](https://github.com/apache/maka/blob/main/llm-compaction-events-log-projection-draft.md) | Detailed projection model and fail-open design | `docs/architecture/` |

## Summary

- **Two-step projection**: Maka compacts context through `selectSafeCompactionPrefix` (safe prefix selection) and `buildHistoryCompactCheckpoint` (checkpoint construction)
- **Immutable ledger**: All operations preserve event immutability and replayability
- **Automatic triggering**: Token estimation via `estimateNextRequestTokens` drives compaction decisions
- **Fail-open safety**: Invalid compactions fall back to uncompacted history with explicit failure markers
- **Deterministic pruning**: Tool pairs and structural boundaries are respected during history reduction
- **Provider flexibility**: V2 text summaries and V3 native states accommodate different LLM capabilities

## Frequently Asked Questions

### What triggers context compaction in Maka?

Maka triggers compaction when `estimateNextRequestTokens` predicts that the next provider call would exceed the model's configured high-water mark. This automatic check runs before each turn, ensuring proactive rather than reactive context management.

### Can I manually force compaction without waiting for automatic triggers?

Yes. Use `kernel.compactSession({ sessionId })` from `@maka/runtime` or invoke the desktop command `sessions:compact`. This creates a new checkpoint immediately, useful for long-running sessions where you want to guarantee available context headroom.

### What happens if the summarizer fails to produce valid output?

Maka follows a fail-open path: the turn receives `context_compaction_failed_open`, the original uncompacted history is sent to the provider, and the session terminates with `context_budget_exhausted`. This guarantees user visibility into the failure while preventing silent data loss.

### Does history pruning break the ability to replay or audit sessions?

No. Pruning operates on the same safe-prefix algorithm as compaction, using deterministic rules that preserve structural integrity. Omitted tool results are replaced with fixed markers, and checkpoints maintain source digests. The full event ledger—including compaction events—remains immutable and reconstructible.