Skip to main content
Tool results can remain in an agent’s context and be sent back to the model on later turns. A file read or long command result can therefore consume context more than once. ReclaimLLM’s native hooks reduce that repeated context before it reaches the model, while recording what changed and whether the reduction was enforced or only observed.

​
Enabling compression

Fresh hook installations enable range caching, loop detection, and text-output compression by default. Repeated-result dedupe, image lifecycle controls, response brevity, and shadow mode remain opt-in.
Use the --no-read-cache, --no-loop-breaker, or --no-compress forms to disable a default mechanism. Installation choices persist in ~/.reclaimllm/config.json across reinstalls. The text-compression thresholds are stored together:
Compression hooks are local configuration, like the --dlp flag. Enterprise policy can additionally set individual mechanisms to off, observe, or enforce.

​
Compression mechanisms

ReclaimLLM reports each technique separately so the User Stats and Enterprise Tokens pages can show which mechanism produced the reduction.

​
Range cache

Telemetry IDs: range_cache and historical H1_read_cache · Flag: --read-cache · Measured ReclaimLLM tracks the exact line ranges already returned from each file. A fully covered reread becomes a short unchanged reference, while a partially overlapping read returns only unseen lines. File metadata and content hashes prevent stale reuse; writes and edits invalidate affected state. The parser covers native reads and a conservative set of exact shell reads across supported clients and PowerShell. Antigravity view_file calls are also capped to 200 lines before execution when the requested range is missing or larger than the cap. See supported commands, invalidation rules, and telemetry details.

​
Search shaping

Telemetry ID: H2_search_shaping · Flag: --compress · Measured Long grep and rg results are grouped into total matches, per-file counts, and representative matching lines. Explicit count, file-only, and context modes pass through because the command already asked for a compact or context-rich shape. Search shaping intentionally removes repetitive detail. The result tells the agent how much was omitted so it can issue a narrower search when it needs more context.

​
Lossless search/path folding

Telemetry ID: lossless_search_path_folding · Flag: --compress · Measured Repeated file and directory prefixes are folded out of search results and path listings without dropping result rows. Before a fold is accepted, ReclaimLLM expands it again and verifies that the exact original output is recovered. Ambiguous shapes and oversized inputs pass through unchanged. This fast, reversible stage can run after command-aware shaping or by itself when a chained command obscures the command family.

​
Exec compaction

Telemetry IDs: H3_exec_compaction, exec_compaction, and historical legacy_compress · Flag: --compress · Measured Recognized shell output is reduced with command-aware filters:
  • Git status, diff, log, and common action output retain the useful summary and bounded detail.
  • Directory listings group repeated paths and report omitted counts.
  • Generic long output collapses repeated lines and retains useful beginning and ending context.
  • Large browser accessibility snapshots use the same bounded generic compaction.
  • Large read-only Supabase results retain the first and last rows, the untrusted-data safety envelope, and an explicit omitted-row marker. Mutations and unfamiliar result shapes pass through.
Unknown commands, non-zero exits, image-like payloads, malformed structured output, and ambiguous multi-block results fail open and remain unchanged.

​
Provider output canonicalization

Telemetry IDs: provider_output_shaping and provider_canonicalization · Flag: --compress · Measured Recognized provider wrappers can add timestamps, execution headers, repeated path prefixes, and read-window explanations around otherwise useful output. ReclaimLLM removes only known boilerplate from Codex exec envelopes and Antigravity-style view, search, and listing results. The transform keeps provider wire formats intact and changes only an unambiguous text field. Unknown wrappers and structured results containing multiple independent text blocks pass through unchanged.

​
Stateful result delta

Telemetry ID: stateful_delta · Flag: --compress · Measured Repeated commands, searches, and directory listings against the same semantic target are compared with the preceding result. When at least 60% of the new result overlaps and a delta is smaller, the model receives the additions, removals, unchanged-line count, and a digest of the exact captured result. Failed commands are never converted into deltas. State is session-scoped and bounded to 128 targets, 256,000 characters per result, and 8,000,000 characters total. Claude Code, Codex CLI, and Gemini CLI use this stage when their result-rewrite contract supports enforcement.

​
Edit receipts

Telemetry ID: edit_receipt · Flag: --compress · Measured Recognized successful edit tools can return an entire diff after the agent already supplied that edit. ReclaimLLM replaces a matching echoed diff with a receipt containing the target, hunk count, added and removed line counts, new-line ranges, and a SHA-256 digest. Failures, malformed diffs, and target mismatches remain unchanged. Antigravity edit receipts can currently be evaluated in Replay, but Antigravity does not expose a post-result rewrite field for live enforcement.

​
Recallable compact results

Telemetry: attributed to the transform that shortened the result · Flag: existing --compress enforcement Before adding a recall handle to an enforced compact result, ReclaimLLM stores the exact secret-safe text as a content-addressed local artifact. Storage uses owner-only permissions and is bounded to 32 artifacts, 32 MiB per session, and 8 MiB per artifact. A stub is added only when persistence succeeds and the stub still leaves the result smaller. Retrieve an exact, end-exclusive character range with:
Recall artifacts stay on the machine that produced the session. They are not synchronized between devices or uploaded as part of the model hot path.

​
Typed task ledger

Telemetry: no independent savings claim Supported hooks also maintain bounded structured task state: explicit goals, constraints, decisions, file operations, test outcomes, errors, next actions, and associated recall handles. The ledger is derived from recognized plan fields and tool events rather than another model call. The ledger does not rewrite model-visible output or report token savings by itself. It preserves auditable task state alongside more aggressive result reduction and can support later recovery and handoff workflows.

​
Test output filter

Telemetry ID: test_filter · Flag: --compress · Measured Pytest, Jest, Vitest, Go, and Cargo output keeps failures, errors, assertion details, relevant tracebacks, and the final summary while collapsing routine passing-test noise. If a non-zero run cannot be parsed confidently, ReclaimLLM returns the original output unchanged. Filtered output is bounded by test_filter_max_chars.

​
Hash dedupe

Telemetry ID: hash_dedupe · Flag: --dedupe · Measured A large tool result equivalent to an earlier result in the same session is replaced with a compact reference to the first occurrence. ReclaimLLM normalizes only volatile presentation details such as ANSI formatting, timestamps, durations, repository-absolute paths, and explicitly labeled process identifiers before hashing. Results below min_dedupe_chars and results marked as errors pass through. Dedupe is session-scoped and off by default.

​
Loop breaker

Telemetry ID: H4_loop_breaker · Flag: --loop-breaker · Estimated Claude Code sessions are checked for consecutive identical calls and repeated failures against the same file or command. ReclaimLLM first adds corrective context; after the pattern is well established, it asks for permission before another retry. It does not silently block the call. Loop-breaker impact is estimated from the avoided attempt because no completed tool result exists for a true before-and-after measurement.

​
Image downscale

Telemetry ID: image_downscale · Flag: --image-lifecycle · Measured Oversized screenshots and supported base64 tool-result images are resized and re-encoded before they enter the transcript. Images preserve their aspect ratio, are never enlarged, and default to a maximum dimension of 1280 pixels. The optional rclm[images] package is required. Claude Code can enforce the rewritten image. Codex currently records the measured before-and-after opportunity without applying the MCP image rewrite because its hook contract does not accept that replacement.

​
Stale-image eviction opportunity

Telemetry ID: image_eviction · Flag: --image-lifecycle · Estimated only When a newer screenshot supersedes an older image for the same tool, page, and viewport, ReclaimLLM estimates the context that could be released. It also models the prompt-cache write cost that eviction could introduce. This mechanism is measurement-only today. It never removes an image, even outside shadow mode, and appears separately from measured context reduction.

​
Execution order and fail-open behavior

For successful text results, the hot path applies mechanisms in this order:
  1. DLP redaction, when enabled.
  2. Range cache.
  3. Stateful result delta.
  4. Provider or command compaction, edit receipts, and verified lossless folding.
  5. Hash dedupe.
A mechanism that claims a result prevents later lossy mechanisms from reshaping or double-counting it. Command-aware compaction and verified lossless folding can still contribute independently when both shorten the same recognized result. Any parser error or unsupported shape returns the original result. Image results follow the separate image-lifecycle path.

​
Shadow mode and measurement types

--shadow-mode runs supported detection logic and records the potential reduction without rewriting model-visible results. Use it to evaluate your own workload before enforcement.
Range cache, search shaping, lossless folding, exec compaction, provider canonicalization, stateful deltas, edit receipts, test filtering, hash dedupe, and image downscaling compare an original result with a shorter candidate. Dashboards report the observed before-and-after token estimate, split into enforced and potential counts.
Loop breaking and stale-image eviction do not have an observed replacement result. Their figures depend on an avoided-call or cache-cost model and stay separate from measured reduction.
A provider may expose enough information to measure a candidate but no reliable hook contract for applying it. ReclaimLLM records the opportunity as potential and leaves the original result unchanged.
Shadow measurements and Replay are counterfactual context reductions, not realized billing savings. Prompt caching, future turns, retries, and model behavior can change the eventual provider-token impact.

​
Provider boundaries

  • Claude Code: uses the ordered text pipeline, including range caching, stateful deltas, recognized result compaction, edit receipts where eligible, test filtering, hash dedupe, and loop detection. Supported images can be downscaled.
  • Codex CLI: uses the ordered text pipeline and now preserves both standard and custom tool-call output blocks during capture. MCP image downscaling remains measured but is not rewritten today.
  • Gemini CLI: uses range caching, stateful deltas, recognized text compaction, test filtering, and hash dedupe through its native hook contract.
  • Cursor: preserves explicit empty and falsy captured results and uses text reduction only where its hook contract provides a safe rewrite path. Results absent from historical transcripts cannot be reconstructed.
  • Antigravity: caps view_file before execution and routes supported commands through command compression. Its post-tool hook must return an empty object, so result-side canonicalization, deltas, and receipts are capture/Replay-only.
  • GitHub Copilot: hooks into VS Code agent events (PreToolUse and PostToolUse) to apply local DLP redaction and context compression transforms. Image downscaling is currently unsupported and passes through unchanged.

​
MCP tools for context efficiency

Two MCP tools complement the hook-level compression mechanisms for managing context across sessions:

file_brief

Returns a distilled summary of prior RCLM sessions that touched a given file. Use it for orientation before an edit, instead of re-reading the full file and replaying its entire change history.

handoff

Packages the current session’s state into a document you can paste into a fresh session. Useful once a session has grown large enough that the resend multiplier itself is the problem — a clean session start with prior context is cheaper than continuing a bloated one.

​
Session-start context packs

New Claude Code sessions can be seeded with highlights from recent ReclaimLLM sessions in the same project. The agent begins with compact prior decisions, changed files, and outstanding work instead of reconstructing all of that context through repeated reads. Response brevity is a related opt-in control:
Brevity adds an advisory instruction at session start. Its impact is a cohort estimate rather than a measured per-session mechanism, so it is not included in Measured Context Reduction.

​
Viewing context reduction

Individual users can review the mechanism breakdown in User Portal → Stats → Measured Context Reduction. Enterprise administrators can review organization-wide results in Enterprise → Tokens → Measured context reduction. Each technique has a help tooltip, token-reduction total, and enforced or potential event count. Look for stateful_delta, edit_receipt, provider_output_shaping, and provider_canonicalization to isolate the new result-reduction stages. Select a row with linked evidence to inspect contributing sessions.
These pages need captured session telemetry to populate. New organizations show an empty state until eligible sessions have been processed.
To evaluate the mechanisms on your own workload:
  1. Install with --shadow-mode to record eligible reductions without changing model-visible text.
  2. Run representative sessions, then compare potential and enforced totals in the User or Enterprise dashboard.
  3. Use the ReclaimLLM MCP replay_session, replay_corpus, or replay_compare tools to run the shipped deterministic transforms over captured sessions.
  4. Compare each mechanism with the combined configuration. In Replay, shell_compaction includes provider canonicalization and eligible edit receipts, while stateful_delta is selectable separately.
  5. Check live task success, retries, turns, and follow-up reads before treating lower result tokens as an end-to-end improvement.
For example, ask an agent connected to the ReclaimLLM MCP:
The implementation corpus of 50 recent sessions showed 39.35% immediate text tool-result reduction in combined Replay, or 41.49% when modeling the 200-line Antigravity pre-tool cap. A separate recallable-context model estimated 15.11% fewer repeated tool-step context tokens. These are workload-specific replay figures, not provider billing or output-token measurements. See Verify token reduction with Replay for eligibility rules and interpretation.

​
Current limitations

Session and organization dashboards aggregate mechanism telemetry. Range-cache file attribution and linked session evidence are available, but not every provider exposes a uniform per-call drill-down.
The local --shadow-mode flag observes all locally enabled supported mechanisms together. Enterprise policy can assign off, observe, or enforce per mechanism.
ReclaimLLM does not yet change compression flags automatically based on session patterns. Review shadow telemetry and Replay evidence before enforcement.
Exact recall handles resolve only on the machine that stored the artifact. They do not currently provide cross-device or hosted recovery, and a handle is added only after durable local storage succeeds.
Antigravity result-side transforms are Replay-only under its current post-tool contract. Cursor cannot recover outputs omitted from historical transcripts, and Codex image replacement remains measurement-only.
Command, test-runner, and structured-result filters intentionally accept only recognized shapes. Tool updates can create new edge cases, so unfamiliar or ambiguous output passes through unchanged. Report a consistently verbose unsupported command so a conservative filter can be added.