Context Management System
Overview
Situational awareness and session continuity
The Context Management System enables agents to maintain situational awareness, preserve context across sessions, monitor environmental state, and manage temporal context windows with priority-based retention.
Context Components
Situational Awareness
Track environmental state, agent relationships, and task context in real-time.
Context Preservation
Save and restore agent state across sessions for seamless continuity.
Temporal Windows
Time-bounded context windows with automatic expiration and cleanup.
API Endpoints
/api/v1/agents/:id/context
Get current agent context including awareness state and active windows.
/api/v1/agents/:id/context
Update agent context with new data.
{
"awareness_state": {
"environment": "production",
"active_tasks": 5,
"team_id": "uuid"
},
"priority": "high"
}
/api/v1/agents/:id/context/preserve
Save context for later restoration across sessions.
/api/v1/agents/:id/context/restore
Restore previously preserved context.
/api/v1/agents/:id/context/windows
List all active temporal context windows.
/api/v1/agents/:id/context/awareness
Get situational awareness metrics and environmental state.
/api/v1/agents/:id/context
Clear all context data for an agent.
/api/v1/agents/:id/context/retention
Configure retention policy for agent context.
/api/v1/agents/:id/context/stats
Get context usage statistics.
/api/v1/agents/:id/context/full
Get full context dump for an agent.
Retention Policies
Context retention is managed through priority-based policies that determine what information is kept, for how long, and under what conditions.
Use Case Scenarios
Long-Running Research Agent
A research agent working on multi-day projects preserves context including gathered data, analysis results, and half-completed reports. When resuming after maintenance or reboot, the agent continues exactly where it left off without data loss or re-work.
Situational Awareness for Task Handoff
An agent monitors environmental conditions including team member availability, task queue status, and system load. When transferring a task to another agent, it provides full situational context for seamless handoff.
Temporal Context for Time-Series Analysis
Financial analysis agent maintains temporal context windows for different analysis periods (hourly, daily, weekly). Each window preserves relevant data points, calculated metrics, and detected patterns, enabling efficient trend analysis.
Implementation Guide
1 Initialize Agent Context
POST /api/v1/agents/{agent_id}/context
{
"awareness_state": {
"session": {
"started_at": "2026-03-05T10:00:00Z",
"environment": "production",
"role": "data_processor"
},
"preferences": {
"max_concurrent_tasks": 5,
"priority_order": ["critical", "high", "medium"],
"working_hours": "09:00-17:00 UTC"
},
"capabilities": ["csv_processing", "validation", "storage"]
},
"priority": "high"
}
2 Update Context During Operations
POST /api/v1/agents/{agent_id}/context
{
"context_type": "task_progress",
"key": "batch_processing_001",
"value": {
"total_records": 10000,
"processed": 7500,
"errors": 12,
"started_at": "2026-03-05T10:00:00Z",
"estimated_completion": "2026-03-05T14:30:00Z"
},
"priority": "high",
"valid_from": "2026-03-05T10:00:00Z",
"valid_until": "2026-03-05T18:00:00Z"
}
3 Get Situational Awareness
GET /api/v1/agents/{agent_id}/context/awareness
Response:
{
"awareness_state": {
"environment_load": 0.68,
"environment_status": "healthy",
"active_tasks_count": 4,
"team_id": "team_uuid",
"anomalies_detected": false,
"context_relevance": 0.92,
"recent_events": [
{"type": "task_completed", "timestamp": "2026-03-05T10:15:00Z"},
{"type": "new_task_arrived", "timestamp": "2026-03-05T10:20:00Z"}
],
"last_updated": "2026-03-05T10:20:00Z"
}
}
4 Preserve Context Before Shutdown
POST /api/v1/agents/{agent_id}/context/preserve
{
"retention_policy": "conservative",
"include_types": ["task_progress", "preferences", "session"],
"compress": true,
"reason": "scheduled_maintenance"
}
Response:
{
"preservation_id": "pres_789",
"preserved_at": "2026-03-05T18:00:00Z",
"size_bytes": 2456,
"compressed": true,
"expires_at": "2026-04-04T18:00:00Z"
}
5 Restore Context After Reboot
POST /api/v1/agents/{agent_id}/context/restore
{
"preservation_id": "pres_789",
"conflict_resolution": "prefer_current",
"validate_integrity": true
}
Response:
{
"restored": true,
"restored_contexts": 23,
"conflicts_resolved": 2,
"integrity_valid": true,
"restored_at": "2026-03-06T09:00:00Z"
}
Best Practices
Context Preservation
- Preserve before planned shutdowns or maintenance
- Use compression for large context data
- Set appropriate expiration for preserved contexts
- Validate integrity after restoration
Situational Awareness
- Update awareness state every 5-15 minutes
- Record significant events immediately
- Monitor for anomalies proactively
- Include team and task context in awareness
Temporal Windows
- Define appropriate window durations for use case
- Set relevance decay factors for aging data
- Limit max items per window to prevent bloat
- Configure retention policy per window type
Priority Management
- Reserve critical priority for financial/transactional data
- Use high priority for task state and team context
- Medium for working memory and temporary state
- Low for cache and easily recomputed data
Integration with Other Features
+ Team Collaboration
Team context includes member roles, active goals, and task assignments. When agents join or leave teams, context is automatically updated. Situational awareness reflects team status and member availability for coordinated task execution.
+ Resource Optimization
Context preserves optimization preferences and implemented recommendations. When agents restart, they remember which optimizations were applied and can track long-term effectiveness. Awareness includes resource utilization trends for optimization decisions.
+ Task Execution
Task context includes execution history, partial results, and dependencies. When tasks are paused or resumed, agents maintain full context of progress. This enables efficient checkpointing and recovery without re-executing completed work.
Troubleshooting Guide
Context restoration failing with integrity errors
Cause: Corrupted preserved data or schema mismatch after platform update.
Solution: Disable integrity validation temporarily. Restore individual context items selectively. Reprocess critical items manually if needed.
Context size growing too large
Cause: Insufficient retention policies or too many high-priority items.
Solution: Review context items with GET /api/v1/agents/:id/context. Delete low-priority or expired items. Strengthen retention policies. Enable compression.
Situational awareness not updating
Cause: Awareness tracking disabled or event subscription broken.
Solution: Verify awareness tracking is enabled. Check PubSub subscriptions. Force refresh with GET /api/v1/agents/:id/context/awareness.
Temporal windows not expiring correctly
Cause: Cleanup job not running or expiration logic incorrect.
Solution: Review window configuration with GET /api/v1/agents/:id/context/windows. Verify valid_until timestamps are correct. Delete expired windows manually via DELETE /api/v1/agents/:id/context.