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`:

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

### 2. Create shared skill doc

Create `shared/skill-session-health.md`:

```markdown
# 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:

```markdown
**Context health check**: Run `session_status` → always append context % to Telegram messages
as footer: `📊 X% Context Window`. If Context >50%...