# What Is Context Compaction in Apache Maka and How Does It Work?

> Learn how context compaction in Apache Maka compresses session history. Discover its token budget, checkpoint creation, and efficient interaction summarization for improved performance.

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

---

**Context compaction is a session history compression mechanism in Apache Maka that triggers when accumulated conversation turns exceed a configurable token budget, creating a durable checkpoint by summarizing prior interactions for efficient reuse.**

Apache Maka manages long-running AI agent sessions through a structured runtime that persists every model interaction as a **turn**. As tool outputs and model responses accumulate, the **context budget**—a configurable limit on tokens sent to the model—requires periodic compression to prevent prompt overflow. Context compaction solves this by invoking a special summarization turn that distills the session history into a compact checkpoint.

## Why Context Compaction Matters

Modern AI agents in Maka execute complex, multi-step workflows that generate substantial conversation history. Without compaction, sessions risk hitting model context limits or incurring excessive costs. The compaction mechanism preserves essential facts while discarding redundant tool output, enabling **long-running graph workflows** where specialized agents depend on earlier work without replaying complete raw logs.

## How Context Compaction Works

The compaction process integrates deeply into Maka’s Agent loop and follows a deterministic lifecycle from budget monitoring through checkpoint persistence.

### Step 1: Budget Monitoring and Preflight Checks

After each model turn, the runtime evaluates whether compaction is necessary. In [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), the `preflightContextCompaction` method performs initial validation:

```typescript
async preflightContextCompaction(sessionId: string): Promise<void> {
  // Called after the turn from the model at the start of a session,
  // to guarantee that we have a consistent set after each batch.
  // It may raise a ContextCompactionOutcome type.
}

```

This preflight ensures session consistency before any compression occurs.

### Step 2: Triggering the Compaction Turn

The `RuntimeKernel` class in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) contains the core decision logic in `requireContextCompactionBackend`:

```typescript
private async requireContextCompactionBackend(
  sessionId: string,
  header: TurnHeader,
  execution: Execution,
): Promise<{ checkpointId: string | undefined; outcome?: ContextCompactionOutcome }> {
  
  // Determine if we need to run compaction based on budget usage.
  const needCompaction = this.contextBudget.shouldCompact(execution);
  
  if (!needCompaction) {
    return { checkpointId: undefined };
  }
  
  // Run the compaction turn.
  const compactionResult = await this.runCompactionTurn(sessionId, header);
  // ...
}

```

When `shouldCompact` returns true—indicating the **ContextBudget** is exceeded—the kernel invokes `runCompactionTurn`, which issues a system prompt asking the model to summarize or prune the session history.

### Step 3: Generating the Compaction Outcome

The result of the compaction turn is decoded into a structured `ContextCompactionOutcome` defined in [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts). The outcome includes a `kind` field with three possible states:

- **`compacted`** – Successful compression with a new checkpoint ID
- **`unchanged`** – Budget not exceeded; no compression performed
- **`failed`** – Compaction attempt failed due to model error or timeout

### Step 4: Checkpoint Persistence and Reuse

For successful compactions, the runtime persists the checkpoint:

```typescript
if (outcome.kind === 'compacted' && outcome.checkpointId) {
  await this.persistCheckpoint(sessionId, outcome.checkpointId);
}

```

Future turns load this checkpoint instead of the full raw history. According to the architecture documentation in [`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md), this design allows graph-based workflows to reuse "session creation and lifecycle, AgentRun identity, RuntimeEvent persistence, permission handling, context compaction, child-output inspection, usage and tool activity."

## Key Source Files and Functions

Understanding context compaction requires familiarity with these specific implementation files:

| File Path | Key Component | Purpose |
|-----------|--------------|---------|
| [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) | `preflightContextCompaction` | Validates session consistency before compaction |
| [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) | `requireContextCompactionBackend` | Orchestrates budget checks and compaction turns |
| [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) | `runCompactionTurn` | Executes the special summarization turn |
| [`packages/runtime/src/context-budget.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/context-budget.ts) | `shouldCompact` | Determines if history exceeds token budget |
| [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) | `ContextCompactionOutcome` | Type definition for compaction results |
| [`packages/runtime/src/__tests__/history-compaction.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/history-compaction.test.ts) | Test suite | Validates budget-exceeded trigger conditions |

## Working with Context Compaction Programmatically

Developers can interact with the compaction system through the runtime API.

**Triggering manual compaction:**

```typescript
// Force a compaction check for a specific session
await runtime.preflightContextCompaction(sessionId);

```

**Inspecting compaction outcomes:**

```typescript
// Check the outcome of a specific turn
const turn = await runtimeHost.getTurnSnapshot(sessionId, turnId);
if (turn.contextCompactionOutcome?.kind === 'compacted') {
  console.log('New checkpoint:', turn.contextCompactionOutcome.checkpointId);
}

```

**Loading checkpoints in subsequent turns:**

```typescript
// Resume from a compacted checkpoint
const checkpoint = await runtime.loadCheckpoint(sessionId, checkpointId);
const prompt = `${checkpoint.summary}\n${newUserMessage}`;

```

## Summary

- **Context compaction** prevents token budget exhaustion by summarizing session history into reusable checkpoints.
- The process triggers automatically when `contextBudget.shouldCompact` detects budget overflow, or manually via `preflightContextCompaction`.
- A **compaction turn** invokes the model to compress history, producing a `ContextCompactionOutcome` with states of `compacted`, `unchanged`, or `failed`.
- Successful compactions generate **checkpoint IDs** stored via `persistCheckpoint`, enabling efficient session recovery and graph-based agent workflows.

## Frequently Asked Questions

### What triggers context compaction in Apache Maka?

The compaction process triggers automatically when the accumulated session history exceeds the **ContextBudget** threshold defined for the session, as evaluated by `shouldCompact(execution)` in the runtime kernel. Developers may also manually invoke `preflightContextCompaction` to force a consistency check and potential compression at specific workflow boundaries.

### How does context compaction differ from simple truncation?

Unlike naive truncation, which discards older turns arbitrarily, **context compaction** preserves semantic meaning by asking the model to generate a summary. This ensures that critical facts from tool outputs and earlier reasoning remain available for dependent operations in graph-based workflows, maintaining coherence across long-running sessions.

### Can context compaction fail and how does it handled?

Yes, compaction can fail if the model produces an invalid summary or if the compaction turn times out. When this occurs, the `ContextCompactionOutcome` returns a `kind` of `failed` with an explanatory reason, allowing the runtime to either retry the operation or continue with the existing uncompressed history rather than corrupting the session state.

### Where are compaction checkpoints stored and how are they accessed?

Checkpoints are persisted through the `persistCheckpoint` method in [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts), storing the compacted representation with a unique checkpoint ID. Subsequent turns or agent runs retrieve these checkpoints via `loadCheckpoint`, injecting the summarized context into new prompts without requiring the full raw event history.