Context Guardian 🛡️

Your context guardian. Alerts before errors happen.

Proactive context monitoring that warns you at 60%, 70%, and 85% usage — before context pollution causes errors and hallucinations.

Why You Need This

The Problem:

Long conversations lead to context pollution
Quality degrades silently as context fills up
You don't know when to restart until it's too late
Errors and hallucinations increase after ~70% usage

The Solution:

Continuous monitoring of context usage
Smart 3-level alerts (⚠️ 60%, 🟠 70%, 🔴 85%)
Actionable suggestions at each level
Prevents duplicate alerts

Quick Start

For Agents: Heartbeat Integration

When you receive a heartbeat poll, include this check:

Call session_status tool to get current context usage
Parse the context percentage from the output
Compare against thresholds: 60% (warning), 70% (danger), 85% (critical)
If threshold exceeded and not a duplicate alert, display the appropriate alert message
Update state file to track alert history

Implementation:

During heartbeat:
1. Get context usage from session_status
2. Check if usage >= 60%, 70%, or 85%
3. Load state from memory/context-guardian-state.json
4. Determine if alert should be sent (prevent duplicates)
5. If yes, display alert and update state

For Users: Enable in HEARTBEAT.md

Add to your HEARTBEAT.md:

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded (60%, 70%, 85%)

The agent will automatically handle the rest.

How It Works

Monitoring

The skill calls session_status to check your current context usage percentage.

Alert Levels

⚠️ Warning (60%)

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

🟠 Danger (70%)

🟠 Context: 70%
Pollution risk rising. Recommend:
• Finish current task
• Start new session for next task
• Or compress with context-optimizer

🔴 Critical (85%)

🔴 Context: 85% - CRITICAL
High error risk. STRONGLY recommend:
• Save work
• Start new session NOW
• Quality degradation likely

Smart Duplicate Prevention

The skill tracks alert history and only alerts when:

First time reaching a threshold
Alert level upgrades (60% → 70% → 85%)
Usage drops below threshold then rises again

Configuration

Edit config/default.json or create config/user.json:

{
  "enabled": true,
  "checkInterval": "heartbeat",
  "thresholds": {
    "warning": 60,
    "danger": 70,
    "critical": 85
  },
  "alertMethod": "message",
  "alertStyle": "emoji",
  "preventDuplicates": true,
  "trackHistory": true,
  "suggestions": {
    "autoSuggest": true,
    "suggestCompression": true,
    "suggestRestart": true
  }
}

Options

checkInterval:

"heartbeat" - Check during heartbeat polls (default)
"cron" - Independent cron job (future)
number - Check every N minutes (future)

thresholds:

Customize alert levels (default: 60, 70, 85)

alertMethod:

"message" - Send as message (default)
"log" - Log only
"notification" - System notification (future)

alertStyle:

"emoji" - Emoji + concise text (default)
"text" - Plain text
"detailed" - Full explanation

Manual Check

You can manually check context status:

bash {baseDir}/scripts/check.sh

Integration with Other Skills

context-optimizer

When you reach 70%, the skill suggests using context-optimizer to compress your context instead of restarting.

context-recovery

After context recovery, the skill automatically resumes monitoring.

Implementation Guide for Agents

Step-by-Step Process

1. Get Context Usage

Call session_status tool and parse the output:

Example output: "Context: 54k/200k (27%)"
Extract: 27

2. Determine Alert Level

if (usage >= 85) level = "critical"
else if (usage >= 70) level = "danger"
else if (usage >= 60) level = "warning"
else level = null

3. Load State

Read {workspace}/memory/context-guardian-state.json:

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": "warning",
  "lastAlertTime": 1709452500,
  "history": [...]
}

4. Check if Should Alert

Prevent duplicate alerts:

shouldAlert = false

// First time reaching threshold
if (!lastAlertLevel && level) shouldAlert = true

// Level upgrade (warning → danger → critical)
if (levelNum[level] > levelNum[lastAlertLevel]) shouldAlert = true

// Usage dropped below threshold and rose again
if (lastUsage < threshold - 5 && usage >= threshold) shouldAlert = true

5. Send Alert

If shouldAlert, display the appropriate message:

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

6. Update State

Save new state to memory/context-guardian-state.json:

{
  "lastCheck": <current_timestamp>,
  "lastUsage": <current_usage>,
  "lastAlertLevel": <level_if_alerted>,
  "lastAlertTime": <timestamp_if_alerted>,
  "history": [..., {"timestamp": <now>, "usage": <usage>}]
}

Alert Messages

Warning (60%):

⚠️ Context: 60%
Getting full. Consider wrapping up or starting fresh soon.

Danger (70%):

🟠 Context: 70%
Pollution risk rising. Recommend:
• Finish current task
• Start new session for next task
• Or compress with context-optimizer

Critical (85%):

🔴 Context: 85% - CRITICAL
High error risk. STRONGLY recommend:
• Save work
• Start new session NOW
• Quality degradation likely

State Management

State is stored in {workspace}/memory/context-guardian-state.json:

{
  "lastCheck": 1709452800,
  "lastUsage": 54,
  "lastAlertLevel": null,
  "lastAlertTime": null,
  "history": [
    {"timestamp": 1709452800, "usage": 54}
  ]
}

Troubleshooting

No alerts appearing:

Check that HEARTBEAT.md includes context monitoring
Verify heartbeat is running
Check state file for errors

Too many alerts:

Increase thresholds in config
Check preventDuplicates is enabled

Alerts not accurate:

Verify session_status is working
Check OpenClaw version compatibility

Examples

Heartbeat Integration

Add to HEARTBEAT.md:

## Context Monitoring
- Check context usage
- Alert if thresholds exceeded

Custom Thresholds

Create config/user.json:

{
  "thresholds": {
    "warning": 50,
    "danger": 65,
    "critical": 80
  }
}

Technical Details

Dependencies:

OpenClaw 2026.2.0+
session_status tool
Bash

Performance:

Zero overhead (only checks during heartbeat)
Minimal state storage (~1KB)

Privacy:

All data stored locally
No external calls
No telemetry

Roadmap

v1.1.0:

Historical trend tracking
Usage prediction
Independent cron mode

v1.2.0:

Auto-trigger context-optimizer
Visual trend graphs
Multi-session monitoring

Contributing

Found a bug? Have a suggestion? Open an issue or PR on GitHub.

License

MIT