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

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, the preflightContextCompaction method performs initial validation:

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 contains the core decision logic in requireContextCompactionBackend:

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. 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:

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, 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	preflightContextCompaction	Validates session consistency before compaction
packages/runtime/src/runtime-kernel.ts	requireContextCompactionBackend	Orchestrates budget checks and compaction turns
packages/runtime/src/runtime-kernel.ts	runCompactionTurn	Executes the special summarization turn
packages/runtime/src/context-budget.ts	shouldCompact	Determines if history exceeds token budget
packages/core/src/events.ts	ContextCompactionOutcome	Type definition for compaction results
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:

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

Inspecting compaction outcomes:

// 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:

// 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, 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.

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