Session Health Monitor

Session Health Monitor

Monitor your OpenClaw agent context window health, get warnings via Telegram when usage is high, save critical facts before compaction, and keep memory directories clean.

Overview

Four capabilities for OpenClaw agent sessions:

1. Context Threshold Warnings — Agents append usage footer to Telegram messages and warn at configurable thresholds 2. Compaction Detection — Track usage drops to infer when context was compacted 3. Pre-Compaction Snapshots — Save key facts and decisions to daily memory files before they're lost 4. Memory Rotation — Archive old daily memory files to prevent clutter

Quick Setup (OpenClaw)

1. Add shared skill reference

Add to your shared/INDEX.md:

| Context window health, compaction detection, pre-compaction snapshots | skill-session-health.md |

2. Create shared skill doc

Create shared/skill-session-health.md:

# Session Health Monitor
Context Health Thresholds
| Level  | Condition                          | Action                        |
|--------|------------------------------------|-------------------------------|
| GREEN  | <50% used AND 0 compactions        | Normal operation              |
| YELLOW | >=50% used OR >=1 compaction       | Save key facts via snapshot   |
| RED    | >=75% used OR >=2 compactions      | Save facts NOW, session ending|
Behavioral Rules
1. When context reaches YELLOW+, extract 3-5 key facts (decisions, files changed, blockers)
2. Run: bash scripts/snapshot.sh "fact1" "fact2"
3. Append footer to Telegram messages at YELLOW+: X% Context Window | Nx compacted
4. Do this BEFORE session ends or context gets compacted
5. After any detected compaction, immediately snapshot what you remember

3. Add heartbeat step

Add to your agent heartbeat/loop:

Context health check: Run session_status → always append context % to Telegram messages
as footer: 📊 X% Context Window. If Context >50% OR Compactions >=1, add:
"⚠️ consider /restart after current task." If Context >75% OR Compactions >=2, flag as urgent.

Context Health Thresholds

| Level | Condition | Action | |--------|----------------------------------------|-------------------------------| | GREEN | <50% used AND 0 compactions | Normal operation | | YELLOW | >=50% used OR >=1 compaction | Consider saving key facts | | RED | >=75% used OR >=2 compactions | Save facts NOW, session ending|

Telegram Message Footer

Agents append a footer to every outgoing Telegram message:

📊 42% Context Window                          # GREEN — no extra warning
📊 63% Context Window | 1x compacted           # YELLOW — consider restart
⚠️ 📊 81% Context Window | 2x compacted        # RED — urgent, save facts

This keeps the user informed about session health without requiring manual checks.

Pre-Compaction Snapshot Protocol

When context reaches YELLOW or above, the agent SHOULD:

1. Extract 3-5 key facts from the current session (decisions made, files changed, blockers found) 2. Write them to memory/YYYY-MM-DD.md using scripts/snapshot.sh 3. Include any unfinished work or next steps 4. Do this BEFORE the session ends or context is compacted

Example snapshot content:

## Pre-Compaction Snapshot (14:32)
Refactored auth module to use JWT instead of sessions (files: src/auth.ts, src/middleware.ts)
Bug found in rate limiter: counter resets on deploy, not on TTL expiry
Next: write tests for new auth flow, fix rate limiter reset logic
Decision: using RS256 for JWT signing (user preference)

When to trigger:

Scripts Reference

context-check.sh

bash scripts/context-check.sh                    # Human-readable output
bash scripts/context-check.sh --json              # Machine-readable JSON
echo '{"context_window":{"used_percentage":72}}' | bash scripts/context-check.sh
Exit codes: 0=GREEN, 1=YELLOW, 2=RED

snapshot.sh

bash scripts/snapshot.sh "Fact one" "Fact two" "Fact three"
echo -e "Fact one\nFact two" | bash scripts/snapshot.sh -

rotate.sh

bash scripts/rotate.sh           # Archives files older than 3 days (default)
KEEP_DAYS=7 bash scripts/rotate.sh  # Keep 7 days instead

Configuration

All configuration is via environment variables with sensible defaults:

| Variable | Default | Description | |----------------------|--------------------------------------------------|----------------------------------------| | MEMORY_DIR | Auto-detect (see below) | Where to write daily memory files | | KEEP_DAYS | 3 | Days to keep before archiving | | HEALTH_GREEN_MAX | 50 | Max % for GREEN status | | HEALTH_RED_MIN | 75 | Min % for RED status | | COMPACTION_DROP | 30 | % drop that indicates compaction |

Memory directory auto-detection order: 1. $MEMORY_DIR environment variable 2. ~/.openclaw/workspace/memory (if exists) 3. ~/.claude/memory (fallback)

Troubleshooting

jq not installed

# macOS
brew install jq
Linux
sudo apt-get install jq

Reset compaction state

rm /tmp/session-health-*.json

Agent not appending footer

All configuration is via environment variables with sensible defaults:

| Variable | Default | Description | |----------------------|--------------------------------------------------|----------------------------------------| | MEMORY_DIR | Auto-detect (see below) | Where to write daily memory files | | KEEP_DAYS | 3 | Days to keep before archiving | | HEALTH_GREEN_MAX | 50 | Max % for GREEN status | | HEALTH_RED_MIN | 75 | Min % for RED status | | COMPACTION_DROP | 30 | % drop that indicates compaction |

Memory directory auto-detection order: 1. $MEMORY_DIR environment variable 2. ~/.openclaw/workspace/memory (if exists) 3. ~/.claude/memory (fallback)

jq not installed

# macOS
brew install jq
Linux
sudo apt-get install jq

Reset compaction state

rm /tmp/session-health-*.json

Agent not appending footer