Context reduction

Context reduction reclaims working material such as old tool output. It is separate from the historian, which turns settled conversation into compartments that remain in the prompt.

Track content with §N§ tags

Every trackable message, file attachment, and tool output receives a §N§ prefix, such as §42§. The agent uses these stable identifiers to tell ctx_reduce which material it has finished using.

Tags are visible in the conversation when ctx_reduce is available to that agent. You do not need to manage them yourself.

Queue a reduction with ctx_reduce

The agent queues one or more tags for removal:

ctx_reduce(drop="3-5,8,12-15")

A queued drop is not necessarily immediate. Magic Context prefers to apply it during a pass that is already rebuilding the prompt cache. This avoids paying for repeated cache rewrites while the agent is still working.

The recent protected window is measured by token mass, not a fixed number of tags. protected_tokens can set the floor explicitly. When you omit it, Magic Context derives a value from the active model’s usable window; for example, 200k usable tokens derive 16k protected tokens, while 1M derives 50k. The older protected_tags setting is deprecated and has no behavioral effect. See the generated configuration reference for the exact range and formula.

When a drop lands, the original content is replaced by a small dropped or truncated marker. The raw transcript remains in the local database for later retrieval.

Reclaim old tool output automatically

Magic Context also has positional, age-based reclaim. It considers tool output from before the last execute boundary, ignores small tool arcs below 250 tokens, and keeps the newest todowrite result plus the newest three ctx_reduce results.

Automatic reclaim has two gates:

1. context pressure has scheduled an execute pass; and
2. that pass is already rebuilding the cache, or emergency recovery is active.

It therefore rides a cache-rebuilding pass but never opens one by itself. This rule applies above the execute threshold as soon as an eligible pass occurs; there is no empty 65%–85% band where all tool output must wait for emergency recovery.

The protected token window still wins during normal reclaim. Recent content stays available even when an older tag count would have made it eligible under the deprecated behavior.

Read the nudge bands

Magic Context compares unreduced, reclaimable tokens with total live-tail tokens. It stays quiet until the live tail is at least 60k tokens and reclaimable content is at least 25k tokens. Above those floors, the ratio selects the reminder:

Reclaimable share of the live tail	Nudge
Below 0.20	Quiet
0.20–0.39	Gentle
0.40–0.59	Firm
0.60 and above	Urgent
0.75 and above, with at least 50k reclaimable tokens	Channel 2 ceiling nudge

Channel 1 reminders appear inline with tool results. Channel 2 is a stronger synthetic steer message. Calling ctx_reduce suppresses further nagging while the agent is actively managing context.

OpenCode

Channel 1 is appended to an eligible tool result as a <system-reminder>. Channel 2 is delivered through OpenCode’s prompt loop as a hidden steer message.

Pi

Channel 1 is appended to an eligible tool result. Channel 2 uses Pi’s steer delivery mode and is hidden from the displayed transcript.

These bands are built-in behavior, not configuration keys.

Know what happens at each pressure band

The execute threshold is a trigger, not a target. At the default 65% threshold, Magic Context can apply queued reductions, heuristic cleanup, age-based reclaim, and ready history updates in one cache-aware pass.

The two emergency bands are not configurable:

Band	What happens	What remains protected
Force band: the greater of 85% or execute threshold + 2 points	Magic Context materializes immediately, bypasses normal mid-tool boundary deferral, and starts an emergency drain. At the default 65% threshold, this begins at 85%; with a 90% threshold, it begins at 92%.	The normal protected token window still applies, along with the reserved newest share of edit, search, and navigation output.
95% absolute emergency	New work blocks while emergency recovery drains context.	Both the protected token window and that newest-tool reserve yield so the session can recover.

The emergency drain remains active until usage falls at least 10 percentage points below the execute threshold, or its 30-minute safety latch expires. These are recovery mechanisms, not normal operating targets.

Note

A high percentage does not identify the cause. Use /ctx-status to separate compartment history, recent conversation, and reclaimable tool output before choosing a lever.

Where a pass lands

The execute threshold answers when to run queued context work, not where the context percentage should land. The default is 65% of the model’s usable, output-reserved window. A pass does not wait for the turn to end; open tool calls waiting for results are never reclaimed, but the pass itself runs as soon as the threshold is crossed.

When an execute pass runs, it applies due work together: queued ctx_reduce drops, heuristic cleanup, eligible age-based tool-output reclaim, and ready history updates. The prompt then becomes stable again at whatever size the retained material requires.

Several independent budgets and boundaries decide where the pass lands:

• The history budget: settled conversation becomes compartments that remain in the prompt under this budget.
• Injected memory text and optional mural: project memory and the memory mural have their own budgets and selection rules.
• The protected recent token window: recent turns stay untouched until they age past the token floor.
• Unsettled live work: in-flight reasoning and messages that have not settled yet remain in the prompt.
• Conversation-vs-tool-output mix: settled conversation condenses into compact history, while tool output can only be dropped or reclaimed.
• Reclaimable tool output: how much tool output was queued with ctx_reduce or was old enough for age-based reclaim.

A session dominated by settled conversation can drop sharply when that conversation condenses into compartments. A session dominated by recent work or unreclaimed tool output may move only a little.

Worked example: a 200k window

Consider a model with a 200k usable context window at the default 65% execute threshold (130k tokens), 15% history budget (19,500 tokens), and derived 16k protected token floor.

Suppose a pass triggers at 140k tokens (70%):

Component	Before pass	After pass	Notes
Fixed prompt and memory	12k	12k	System instructions and injected memory stay stable
Compartment history	12k	19k	Settled conversation condenses into the history budget
Settled conversation	48k	0k	Replaced by new compartment summaries
Protected recent work	28k	28k	Protected by the recent token window
Tool output	40k	31k	9k queued or eligible output reclaimed
Total	140k (70%)	90k (45%)	Remaining context

The next prompt is 90k tokens, or 45%: 12k fixed prompt and memory + 19k history + 28k recent work + 31k tool output. It landed at 45% because those retained inputs totaled 90k—not because 45% was a target.

There is no target-size setting

You can change when a pass triggers with the per-model execute threshold, improve agent-driven cleanup with ctx_reduce, choose a stronger historian model, and align cache assumptions with cache_ttl. None of these configures a post-pass landing percentage. See the generated configuration reference for exact keys and ranges.

Enable smart drops when useful

smart_drops is optional and off by default. When enabled, it adds content-aware selection to a pass that is already rebuilding the cache:

• keeps only the newest todowrite result and newest three spent ctx_reduce results;
• drops zero-value bash_status, bash_kill, and ctx_note read or dismiss results;
• replaces older edits or writes to the same file with a small marker that preserves the file path, while keeping the newest edit full.

Smart drops honor normal protection and never initiate a cache rewrite. Enable the setting in magic-context.jsonc, then restart the harness. See the configuration reference for the source-generated description.

Hide the reduce surface

Deny or omit ctx_reduce from a specific agent’s tool allow-list to remove the agent-facing reduction surface for that session. Magic Context then omits visible §N§ prefixes, reduction guidance, and both nudge channels for that agent.

Deterministic management still runs: the historian, heuristic cleanup, age-based reclaim during eligible cache-rebuilding passes, emergency recovery, compartment injection, and memory remain available. See Session modes for the broader feature comparison.

Diagnose a surprising percentage

Use the contrast in Overview and the breakdown in Where a pass lands to inspect what is using space. If conversation dominates, look at historian progress and the history budget. If tool output dominates, let the agent call ctx_reduce and check whether an eligible cache-rebuilding pass has occurred. If recent work dominates, it is intentionally protected until it ages out.