Context Management
Context management is a core feature of Trinity Framework 2.0 that helps manage AI model context limitations, enabling smooth operation across context resets. This guide explains how to set up and use the context management system effectively.
Note: While context management is optional in Trinity Framework 2.0 Core, it is highly recommended for stable long-term agent operation.
Understanding Context Limitations
Claude and other AI models have finite context windows that limit how much information they can process at once. When this limit is reached, a context reset occurs, which can disrupt operational continuity.
The Trinity Framework's context management system addresses these limitations by:
- Tracking context utilization in real-time
- Creating checkpoints at critical thresholds
- Providing recovery mechanisms after context resets
- Visualizing remaining context capacity
Context Management Components
Context Tracker
Monitors token usage and detects threshold crossings
- Estimates token usage for operations
- Tracks utilization percentage
- Detects threshold crossings
Checkpoint Manager
Creates and manages serialized state checkpoints
- Creates checkpoints at thresholds
- Stores checkpoint metadata
- Manages checkpoint lifecycle
Recovery System
Handles post-compact recovery automatically
- Detects context resets
- Restores from checkpoints
- Rebuilds operational awareness
Visualization System
Provides visual representation of context status
- Creates progress bar visualization
- Shows remaining operations
- Indicates threshold levels
Setting Up Context Management
Step 1: Install Dependencies
The context management system requires Node.js. Ensure you have it installed, then run:
$ ./install-dependencies.sh
✓ Dependencies installed successfully!
✓ Context management system ready
Step 2: Configure AUTO-COMPACT.md
Ensure your AUTO-COMPACT.md file includes the following at the top:
Execute after EVERY response:
```bash
cd /path/to/workspace/tools/token-tracker/context-manager-v2/bin
./run-context-check.sh check ASSISTANT_MEDIUM # Adjust type as needed
```
Step 3: Verify Installation
Test the context management system by running:
$ ./run-context-check.sh check ASSISTANT_SMALL
[Context: 10% ▓▓░░░░░░░░░░░░░░░░░░] Remaining: ~122 small operations
Using Context Management
Operation Types
The context management system uses different operation types to estimate token usage:
| Category | Operation Type | Estimated Tokens | Usage |
|---|---|---|---|
| User Messages | USER_SMALL | ~750 tokens | Brief messages |
| USER_MEDIUM | ~2200 tokens | Standard messages | |
| USER_LARGE | ~4400 tokens | Detailed messages | |
| Assistant Responses | ASSISTANT_SMALL | ~1500 tokens | Brief responses |
| ASSISTANT_MEDIUM | ~4400 tokens | Standard responses | |
| ASSISTANT_LARGE | ~10000 tokens | Detailed responses | |
| Tool Operations | TOOL_READ_SMALL | ~1500 tokens | Small file reads |
| TOOL_READ_MEDIUM | ~4400 tokens | Medium file reads | |
| TOOL_READ_LARGE | ~7500 tokens | Large file reads | |
| TOOL_TASK | ~6000 tokens | Task tool executions |
Tracking Context Usage
After each response, run the context check command:
This will output a visualization of current context utilization:
Threshold Levels
The context management system defines three threshold levels:
- NOTICE (65%): Early warning, consider wrapping up complex tasks
- WARNING (75%): Create checkpoints, prepare for potential reset
- ALERT (85%): Imminent reset risk, offer auto-compact option
Creating Checkpoints
Checkpoints are automatically created at threshold crossings, but you can manually create them:
✓ Checkpoint created: ckpt_manual_20250613
Recovery After Context Reset
Automatic Recovery
After a context reset, run the recovery command:
✓ Checkpoint found: ckpt_warning_20250613
✓ Restored from checkpoint (context: 75%)
Auto-Compact Detection
The system can automatically detect context resets:
✓ Auto-compact detected at 2025-06-13T14:30:15.000Z
✓ Recovery state prepared
Continuous Monitoring
For long-running sessions, you can enable continuous monitoring:
✓ Monitoring started (60-second interval)
✓ Press Ctrl+C to stop monitoring
Advanced Usage
Generating Reports
Generate context utilization reports:
✓ Report generated: context-report-20250613.md
Resetting Tracking State
To reset tracking state (rarely needed):
✓ Context tracking state reset
Customizing Thresholds
Adjust thresholds in the configuration file:
Best Practices
- Consistent Tracking: Always include context tracking with every response
- Appropriate Operation Types: Use the correct operation type for accurate estimates
- Regular Checkpoints: Create checkpoints at meaningful progress points
- Early Warning Response: Take action when reaching NOTICE threshold
- Status Updates: Include context health in STATUS.md updates
Important: Don't ignore WARNING and ALERT thresholds. They provide critical opportunities to create checkpoints before resets occur.
Troubleshooting
Common Issues
| Issue | Possible Cause | Solution |
|---|---|---|
| Missing tracking output | Incorrect path or permissions | Verify paths and permissions in AUTO-COMPACT.md |
| Inaccurate estimates | Wrong operation type | Use appropriate operation type for message size |
| Failed checkpoint creation | Disk space or permissions | Check available space and directory permissions |
| Failed recovery | Corrupted checkpoint data | Use an earlier checkpoint or reset tracking |
Viewing Logs
Check logs for detailed troubleshooting information:
For More Information
For advanced context management features, see the Interactive Token Tracking guide.
← Back to Documentation Home