Skip to content

context-compression.md

Latest commit

 

History

History
65 lines (46 loc) · 2.35 KB

context-compression.md

File metadata and controls

65 lines (46 loc) · 2.35 KB
Raw

Context Compression

Context compression is an optional layer for shrinking supporting evidence in context packs. It never replaces exact diagnostics required to fix a failing check.

Default context packs remain deterministic and bounded without external services. Compression is opt-in through either CLI flags or [tool.agent_maintainer] configuration.

Built-In Backends

Agent Maintainer includes deterministic built-in compression backends:

  • none: keep supporting context unchanged.
  • truncate: keep a bounded prefix.
  • extractive: keep lines selected from supporting context.

The compression interface preserves required terms. If a backend drops a required preserve term, Agent Maintainer falls back to deterministic extractive compression.

Optional Headroom Backend

Headroom support is optional and experimental in beta. Keep deterministic backends as the default unless you explicitly want to test provider-backed compression on sanitized supporting context.

Install optional Headroom support explicitly:

python -m pip install "agent-maintainer[compression]"

Run a context pack with Headroom compression:

python -m agent_maintainer context pack --compress headroom

Require Headroom compression instead of falling back:

python -m agent_maintainer context pack --compress headroom --require-compression

When Headroom is missing and compression is required, the command fails with installation guidance. When Headroom fails and compression is not required, Agent Maintainer warns and uses deterministic extractive compression.

Safety Boundary

Optional providers receive only sanitized supporting context from selected logs and file outlines, passed as a single Headroom-compatible user message. They do not receive exact repair facts, structured manifests, ratchet fingerprints, change-plan scopes, or raw unredacted logs.

Headroom results also cross a runtime-validated boundary before they enter a context pack. The adapter accepts plain text, string-keyed result objects, and message arrays with string content. Malformed neighboring messages are skipped; an unsupported result shape raises a compression-backend error and follows the configured required-compression or deterministic-fallback behavior.