# How Headroom Context Tracker Prevents Context Amnesia in Multi-Turn Conversations

> Headroom Context Tracker prevents context amnesia by caching compression events, analyzing new queries, and expanding content. Learn how it maintains conversational memory.

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

---

**Headroom’s Context Tracker prevents context amnesia by recording every compression event in a bounded LRU cache, analyzing new queries for relevance against stored metadata, and automatically expanding previously compressed content when needed, all while maintaining strict project isolation via workspace keys.**

The `chopratejas/headroom` repository implements a sophisticated **Context Tracker** as part of its CCR (Compress-Cache-Retrieve) pipeline to solve the problem of "context amnesia" in long-running LLM conversations. This component ensures that once information is compressed to save token space, it can be intelligently recalled when relevant to future queries, preventing the model from forgetting critical details across conversation turns.

## Understanding Context Amnesia in the CCR Pipeline

Context amnesia occurs when an LLM loses access to previously discussed information after it has been compressed or removed from the active context window to manage token limits. In [`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py), the Context Tracker counters this by maintaining a persistent registry of compressed content that survives beyond a single turn, enabling the system to retrieve "forgotten" data when needed.

## Five Mechanisms That Prevent Amnesia

### Recording Compression Events with track_compression

Every time content is compressed, the tracker invokes `track_compression()` to create a `CompressedContext` entry. This stores the hash of the compressed payload, turn number, original and compressed item counts, the triggering query, and a preview of sample content. According to the source code in [`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py) (lines 10-18), this creates an immutable audit trail of what was removed from the active context.

### Memory-Bounded Storage via LRU Cache

The tracker maintains an internal `_contexts` dictionary that behaves as a least-recently-used (LRU) cache. With a default `max_tracked_contexts` of 100, the system evicts older entries when the limit is exceeded, guaranteeing predictable memory usage while preserving the most recent interactions. This prevents unbounded growth while keeping recent context alive.

### Query Analysis and Relevance Scoring

When new queries arrive, the `analyze_query()` method extracts keywords and scores them against the `sample_content` of all stored `CompressedContext` entries. The system generates `ExpansionRecommendation` objects for any matches exceeding the `relevance_threshold` of 0.3 (default), identifying which compressed data might be relevant to the current conversation turn.

### Proactive Context Expansion

If `proactive_expansion` is enabled in the configuration, the tracker automatically expands up to `max_proactive_expansions` relevant contexts per turn before the LLM generates a response. This re-introduces previously compressed data into the prompt before the model processes the query, effectively eliminating the gap where "forgotten" information would otherwise be needed.

### Workspace Isolation for Security

Every `CompressedContext` carries a `workspace_key` that isolates data per project (lines 39-48 in [`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py)). The tracker only expands contexts sharing the same workspace as the current request, preventing cross-project leakage and ensuring that sensitive information from one project does not contaminate another.

## Practical Implementation

The following example demonstrates initializing a tracker, recording a compression event, and analyzing a follow-up query:

```python

# Initialise a tracker (uses default configuration)

from headroom.ccr.context_tracker import ContextTracker

tracker = ContextTracker()

# After a search/compression step, record what was compressed

tracker.track_compression(
    hash_key="abc123",
    turn_number=1,
    tool_name="Bash",
    original_count=120,
    compressed_count=12,
    query_context="find all python source files",
    sample_content='["src/main.py", "src/auth.py", "src/utils.py"]',
    workspace_key="my-project",
)

# Later, when the user asks a follow‑up question

recommendations = tracker.analyze_query(
    query="How does the authentication flow work?",
    current_turn=5,
)

# The tracker may suggest expanding the earlier compression:

for rec in recommendations:
    if rec.expand_full:
        # Load the full content from the compression store and add it to the prompt

        full_items = get_compression_store().load_full(rec.hash_key)
        prompt.extend(full_items)

```

## Key Source Files and Architecture

- **[`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py)**: Implements `CompressedContext`, `ContextTrackerConfig`, and the `ContextTracker` class that records compressions and decides when to expand them.
- **[`headroom/ccr/batch_store.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/batch_store.py)**: Stores per-turn `BatchContext` objects that the tracker queries for relevance.
- **[`headroom/cache/compression_store.py`](https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py)**: Provides the persistence layer where the full, uncompressed data lives and can be re-loaded on demand.
- **[`headroom/ccr/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/__init__.py)**: Exposes the CCR API, including the context-tracking entry point used by the proxy server.

## Summary

- The Context Tracker records every compression via `track_compression()`, creating immutable metadata entries including hash keys, turn numbers, and sample content.
- An LRU cache with default limit of 100 entries ensures bounded memory usage via `max_tracked_contexts`.
- The `analyze_query()` method scores new queries against stored samples using a default `relevance_threshold` of 0.3.
- Proactive expansion settings allow automatic re-insertion of relevant compressed content before LLM generation when `proactive_expansion` is enabled.
- Workspace keys enforce project isolation, preventing cross-contamination of context between different projects.

## Frequently Asked Questions

### What is context amnesia in Headroom?

Context amnesia refers to the phenomenon where an LLM loses access to previously provided information after it has been compressed out of the active context window to save tokens. Headroom's Context Tracker prevents this by maintaining a registry of compressed content and automatically re-expanding it when relevant to new queries, ensuring continuity across long conversations.

### How does the Context Tracker decide which compressed content to expand?

The tracker uses `analyze_query()` to extract keywords from incoming queries and match them against the `sample_content` of stored `CompressedContext` entries. Matches exceeding the `relevance_threshold` (default 0.3) generate `ExpansionRecommendation` objects, which trigger expansion if proactive expansion is enabled or can be used for manual retrieval.

### What limits the memory usage of the Context Tracker?

The internal `_contexts` dictionary operates as a bounded LRU cache controlled by `max_tracked_contexts`, which defaults to 100 entries. When this limit is reached, the least recently used compressed context entries are evicted, ensuring predictable memory consumption regardless of conversation length.

### Can compressed contexts from different projects leak into each other?

No. The `workspace_key` parameter in every `CompressedContext` ensures strict isolation. The tracker only considers contexts for expansion when they share the same `workspace_key` as the current request, preventing cross-project context leakage as implemented in lines 39-48 of [`headroom/ccr/context_tracker.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/context_tracker.py).