cleveragents-core/docs/reference/skeleton_compressor.md

Skeleton Compressor

Overview

The Skeleton Compressor produces a compressed representation of a plan's accumulated context for propagation to child plans as inherited context. Compression is governed by the skeleton_ratio budget parameter set on a project's context policy.

The compressor lives in cleveragents.application.services.skeleton_compressor.SkeletonCompressorService and is registered in the DI container as skeleton_compressor_service.

Skeleton Ratio

Ratio	Meaning	Behaviour
0.0	No compression	All fragments pass through unchanged.
0.3	Default	~70 % of tokens retained (top-relevance first).
0.5	Moderate	~50 % of tokens retained.
0.8	Heavy	~20 % of tokens retained.
1.0	Maximum	Only the single highest-relevance fragment is kept.

The ratio is validated to the closed interval [0.0, 1.0]. Values outside this range raise ValueError.

Default Handling

When a plan or project context policy does not set skeleton_ratio, the service applies the constant DEFAULT_SKELETON_RATIO = 0.3.

Fragment Ordering

Fragments are sorted by relevance descending with a stable secondary sort on fragment_id ascending. This guarantees deterministic output: identical inputs always produce identical compressed payloads regardless of the order in which fragments arrive.

Compression Algorithm

1. Validate all inputs (ratio, fragment fields).
2. Compute original_tokens — sum of token_count across all fragments.
3. Sort fragments by (-relevance, fragment_id).
4. Compute a token budget: budget = original_tokens * (1 - ratio).
5. Iterate sorted fragments, accumulating tokens until the budget is exhausted.
6. Return the kept fragments and a SkeletonMetadata record.

Metadata

Every compression pass produces a frozen SkeletonMetadata:

Field	Type	Description
ratio	float	The ratio applied.
original_tokens	int	Tokens before compression.
compressed_tokens	int	Tokens after compression.
source_decision_ids	tuple[str, ...]	Decision ULIDs included.

The metadata is persisted on the Plan model via the skeleton_metadata field, making compression auditable.

Compression Summary

The metadata doubles as a compression summary: compare original_tokens to compressed_tokens to see how much context was removed. The summary is included in plan status CLI output under the skeleton key.

Example: Multi-Decision Plan

Consider a plan with three decision context fragments:

Fragment A  (relevance=0.9, tokens=400, decision=01HX...)
Fragment B  (relevance=0.6, tokens=300, decision=01HY...)
Fragment C  (relevance=0.3, tokens=300, decision=01HZ...)

With skeleton_ratio = 0.5 the token budget is 1000 * (1 - 0.5) = 500 tokens:

• Fragment A (400 tokens, cumulative 400) — kept.
• Fragment B (300 tokens, cumulative 700) — exceeds budget; skipped.

Result:

Compressed fragments: [A]
original_tokens: 1000
compressed_tokens: 400
source_decision_ids: (01HX...)

Integration

The skeleton output feeds into the subplan context inheritance pipeline. When a parent plan spawns a child, the strategy coordinator calls the compressor on the parent's accumulated context, stores the resulting SkeletonMetadata on the child plan, and passes the compressed fragments as the child's inherited context budget.

CLI

The --skeleton-ratio flag on agents project context set sets the ratio for a project's context policy. The plan status command displays the compression summary when skeleton_metadata is present.