# How IntelligentContext Scores Message Importance in Headroom

> Learn how IntelligentContext scores message importance using six key dimensions to effectively manage token budgets. Understand the weighted sum for optimal message retention.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-16

---

**IntelligentContext computes a composite importance score for each message using a weighted sum of six dimensions—recency, semantic similarity, TOIN importance, error indicators, forward references, and token density—to determine which messages to retain when token budgets are exceeded.**

Headroom's *IntelligentContext* transform replaces the naive "drop-oldest-first" truncation policy with a multi-factor scoring system. According to the `chopratejas/headroom` source code, every message in a conversation receives a normalized score between 0 and 1 that reflects its value for the next model call. Messages scoring below the threshold are moved to the CCR (Cross-Conversation Retrieval) cache, while high-scoring messages remain in the active context window regardless of age.

## The Six Dimensions of Message Importance

The scoring algorithm evaluates six distinct metrics, each weighted according to the `ScoringWeights` dataclass defined in [`docs/spec/008-capabilities.md`](https://github.com/chopratejas/headroom/blob/main/docs/spec/008-capabilities.md) (lines 30-38).

### Recency

**Recency** applies an exponential decay function based on the message's position relative to the latest turn. The calculation uses `exp(-λ * distance_from_end)`, where λ represents the `recency_decay_rate` (default **0.1**). Newer messages receive higher scores, but the decay rate prevents recent yet irrelevant messages from dominating the context.

### Semantic Similarity

**Semantic similarity** measures topical relevance by computing the cosine similarity between the message's embedding and the aggregated embedding of the most recent context window. The embedder used is determined by the `HEADROOM_EMBEDDER_RUNTIME` configuration. Messages discussing topics aligned with the current conversation receive elevated scores.

### TOIN Importance

**TOIN importance** leverages learned retrieval statistics from the Telemetry-TOIN subsystem. It calls `toin.retrieval_rate(message_signature)` to determine how frequently a specific message pattern has been retrieved via `ccr_retrieve` in previous interactions. Patterns that the model frequently recalls are deemed more valuable, with a default weight of **0.25**—the highest of any dimension.

### Error Indicators

**Error indicators** identify messages where `field_semantics.inferred_type == "error_indicator"` according to TOIN telemetry. These represent previous errors or failed attempts that the model struggled with. Retaining these messages prevents the model from repeating mistakes, applying a default weight of **0.15**.

### Forward References

**Forward references** count how many subsequent messages explicitly reference a given message ID (for example, through tool arguments or quotations). Messages that serve as anchors for later reasoning receive higher scores, reflecting their structural importance to the conversation flow.

### Token Density

**Token density** calculates the ratio of `unique_tokens / total_tokens`. Information-dense messages (those with high lexical diversity) are preferred over repetitive or verbose content, though this dimension carries the lowest default weight of **0.05**.

## How the Composite Score Is Calculated

The final importance score is computed as a weighted sum:

```

score = Σ (weight_i × normalized_metric_i)

```

The `ScoringWeights` configuration class normalizes all user-provided values to ensure they sum to **1.0**, as documented in [`wiki/configuration.md`](https://github.com/chopratejas/headroom/blob/main/wiki/configuration.md) (lines 26-34). During each turn, [`headroom/transforms/intelligent_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/intelligent_context.py) calculates each dimension for every stored message, normalizes the metrics, and applies the weights.

Messages are sorted **ascending** by this composite score. The lowest-scoring messages are dropped first, while the highest-scoring messages are retained—even if they are significantly older than other candidates. Dropped messages are stored in the CCR cache and recorded back to TOIN, creating a feedback loop that increases the importance scores of patterns users retrieve later (see [`wiki/ARCHITECTURE.md`](https://github.com/chopratejas/headroom/blob/main/wiki/ARCHITECTURE.md), lines 76-94).

## Configuration and Customization

You can override the default weights and decay parameters through `IntelligentContextConfig`. The default weights are:

- **Recency**: 0.20
- **Semantic similarity**: 0.20
- **TOIN importance**: 0.25
- **Error indicator**: 0.15
- **Forward reference**: 0.15
- **Token density**: 0.05

The `recency_decay_rate` (default **0.1**) controls how quickly recency scores degrade, as specified in [`wiki/configuration.md`](https://github.com/chopratejas/headroom/blob/main/wiki/configuration.md) (lines 50-52). Lower values favor older messages, while higher values enforce stricter recency bias.

## Code Examples

Create a custom scoring configuration with adjusted weights:

```python
from headroom.config import IntelligentContextConfig, ScoringWeights

weights = ScoringWeights(
    recency=0.15,
    semantic_similarity=0.25,
    toin_importance=0.30,
    error_indicator=0.15,
    forward_reference=0.10,
    token_density=0.05,
)

ic_config = IntelligentContextConfig(
    enabled=True,
    use_importance_scoring=True,
    scoring_weights=weights,
    toin_integration=True,
    recency_decay_rate=0.08,          # faster decay

    output_buffer_tokens=3000,
)

from headroom.telemetry import get_toin
from headroom.transforms import IntelligentContextManager

toin = get_toin()
manager = IntelligentContextManager(config=ic_config, toin=toin)

messages = [...]                     # list of dicts {role, content, ...}

kept, dropped = manager.apply(messages)

print(f"Kept {len(kept)} messages, dropped {len(dropped)}")

# Dropped messages are automatically stored in CCR for later retrieval

```

For minimal configuration changes, override specific weights:

```python
from headroom.transforms import IntelligentContextManager
from headroom.config import IntelligentContextConfig, ScoringWeights

cfg = IntelligentContextConfig(
    scoring_weights=ScoringWeights(toin_importance=0.40)  # prioritize TOIN learned importance

)

manager = IntelligentContextManager(config=cfg, toin=get_toin())

```

## Summary

- **IntelligentContext** replaces FIFO truncation with importance-based scoring in `chopratejas/headroom`.
- The composite score combines six dimensions: recency, semantic similarity, TOIN importance, error indicators, forward references, and token density.
- **TOIN importance** (default weight 0.25) is the primary factor, learned from historical retrieval patterns via `toin.retrieval_rate()`.
- Scoring weights are defined in `ScoringWeights` and normalized to sum to 1.0, with configuration documented in [`docs/spec/008-capabilities.md`](https://github.com/chopratejas/headroom/blob/main/docs/spec/008-capabilities.md) and [`wiki/configuration.md`](https://github.com/chopratejas/headroom/blob/main/wiki/configuration.md).
- The implementation resides in [`headroom/transforms/intelligent_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/intelligent_context.py), integrating with TOIN telemetry and CCR caching as described in [`wiki/ARCHITECTURE.md`](https://github.com/chopratejas/headroom/blob/main/wiki/ARCHITECTURE.md).

## Frequently Asked Questions

### What is the exact formula for IntelligentContext importance scoring?

The formula is `score = Σ (weight_i × normalized_metric_i)`, where each `metric_i` represents one of the six dimensions (recency, semantic similarity, TOIN importance, error indicators, forward references, token density). Each metric is normalized to a 0-1 scale before weighting, and the weights are defined in the `ScoringWeights` dataclass. The configuration class automatically normalizes user-provided weights so they sum to 1.0.

### How does the TOIN telemetry system influence which messages are kept?

TOIN (Telemetry-Optimized Information Network) tracks how often specific message patterns are retrieved via `ccr_retrieve`. The `toin.retrieval_rate(message_signature)` function returns a learned statistic indicating historical importance. Messages with high retrieval rates receive higher scores, ensuring that information the model frequently references remains available even if it is not recent.

### Can I customize the recency decay behavior in Headroom?

Yes. The `recency_decay_rate` parameter in `IntelligentContextConfig` controls the λ value in the exponential decay function `exp(-λ * distance_from_end)`. The default value is **0.1**, but you can increase it to favor very recent messages or decrease it to retain older messages longer. This configuration is documented in [`wiki/configuration.md`](https://github.com/chopratejas/headroom/blob/main/wiki/configuration.md) (lines 50-52).

### What happens to messages that are dropped from the context window?

Dropped messages are automatically stored in the CCR (Cross-Conversation Retrieval) cache and recorded back to TOIN. This creates a feedback loop where messages that users or the system retrieve later receive increased importance scores in future interactions. This mechanism ensures that dropped content can be recovered if needed and that the importance scoring improves over time based on actual usage patterns.