Context Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/core/contextManager.ts
• src/core/conversationManager.ts
• src/core/agent.ts
• src/core/toolManager.ts
• tests/contextManager.spec.ts

Context Management is the system responsible for monitoring, compressing, and pruning the conversation history within the Autohand CLI. Its primary purpose is to ensure that interactions remain within the Large Language Model's (LLM) token limits while preserving critical project information, decisions, and file content. This module provides "unlimited context" through a tiered approach to reduction: compression of verbose outputs, summarization of old turns, and aggressive priority-based cropping.

The system interacts closely with the ConversationManager to modify history and the Agent to provide status updates to the user. By analyzing message metadata—such as file paths, tool calls, and decision patterns—the manager can selectively remove low-priority information (like long raw tool outputs) while keeping high-priority content (like system instructions and recent user requests).

Architecture and Tiered Reduction

The context management logic follows a tiered strategy based on current context window usage. As the token count approaches the model's limit, the system escalates its intervention.

Threshold Tiers

Tier	Threshold	Action
Tier 1	70% Usage	Compression: Trims verbose tool outputs (>2000 chars) while keeping headers/tails.
Tier 2	80% Usage	Summarization: Condenses older conversation turns into a system-note summary.
Tier 3	90% Usage	Aggressive Cropping: Removes low-priority messages until 65% usage is reached.

Sources: src/core/contextManager.ts:16-21, src/core/contextManager.ts:80-112

Context Lifecycle Flow

The following diagram illustrates how a request is prepared before being sent to the LLM:

The flow ensures that every request is validated against the model's token window before execution.
Sources: src/core/contextManager.ts:80-112

Priority-Based Management

When aggressive cropping (Tier 3) is required, messages are not removed chronologically. Instead, they are sorted by a calculated priority, ensuring that system instructions and critical decisions remain in context as long as possible.

Message Priority Levels

• Critical: System messages and user messages containing explicit decisions or preferences.
• High: Recent user messages, error reports from tools, and assistant-made decisions.
• Medium: Standard conversation flow and tool outputs containing file reads.
• Low: Verbose tool outputs and long background information.

Sources: src/core/contextManager.ts:315-345, tests/contextManager.spec.ts:60-88

Priority Ranking Algorithm

The system uses sortMessagesByPriority to identify removal candidates:

1. Priority First: Messages with 'low' priority are targeted first.
2. Age Second: Within the same priority level, older messages are removed first.
3. Protected: The system never removes the system message (index 0) or the very last user message.

Sources: src/core/contextManager.ts:466-487, src/core/contextManager.ts:192-205

Smart Summarization and Metadata

Instead of simply deleting history, the ContextManager extracts metadata to create "intelligent summaries" that are re-injected into the conversation.

Metadata Extraction

The system scans messages for:

• Files: Paths like src/index.ts or package.json.
• Tools: Names of tools invoked (e.g., read_file, git_commit).
• Decisions: Phrases indicating the agent chose a specific path (e.g., "I'll use TypeScript").
• Errors: Indicators of failure like TypeError or ❌.

Sources: src/core/contextManager.ts:258-309, tests/contextManager.spec.ts:14-58

This diagram represents the relationship between the Manager, the Message data structure, and the extracted Metadata used for summarization.
Sources: src/core/contextManager.ts:33-40, src/types.js

Integration with Agent Loop

The AutohandAgent utilizes the ContextManager within its ReAct loop. It monitors contextPercentLeft and can trigger a manual smart_context_cropper tool if the model itself decides history should be trimmed.

Context Statistics in UI

The agent provides real-time feedback to the user via the status line:

• Warning Threshold: If usage exceeds a threshold, the CLI displays a warning.
• Critical Threshold: If usage hits critical levels, the agent auto-crops and logs: "Context at critical level, auto-cropping old messages...".

Sources: src/core/agent.ts:1010-1045, src/core/agent.ts:1105-1120

The smart_context_cropper Tool

The LLM can also explicitly manage its own context using a dedicated tool:

{
  name: 'smart_context_cropper',
  description: 'Trim conversation history when context is full',
  parameters: {
    type: 'object',
    properties: {
      crop_direction: { type: 'string', enum: ['top', 'bottom'] },
      crop_amount: { type: 'number' },
      deleted_messages_summary: { type: 'string' }
    }
  }
}

Sources: src/core/toolManager.ts:375-385, src/core/agent.ts:984-1008

Conclusion

Context Management is vital for the stability of the Autohand CLI. By implementing tiered reduction and priority-based selection, the system prevents "Context Window Exceeded" errors while ensuring that the agent retains the most relevant information for completing complex, multi-step software engineering tasks. Re-injecting summaries of cropped content allows the model to maintain a "compressed memory" of previous steps in the session.