| name | session-watchdog |
| description | Monitor session context levels and proactively save checkpoints before compaction. Use when: (1) session context exceeds 80% capacity, (2) user asks about session status or memory, (3) at the start of each new session to check context, or (4) before long tasks that might push context over threshold. |
Session Watchdog
Monitors context levels, warns before compaction, and saves checkpoints to preserve important information.
Context Thresholds
| Level | Tokens | Action |
|---|
| Safe | 0-140k | Normal operation |
| Warning | 140k-160k | Warn user, save checkpoint |
| Critical | 160k-197k | Warn + stop unless urgent |
| Full | 197k+ | Compaction imminent |
Check Context
Before each session and periodically during long conversations:
session_status
Check the contextTokens field from the response.
Checkpoint Protocol
When approaching 80% (160k tokens):
-
Save checkpoint to memory file:
- Read current memory/YYYY-MM-DD.md
- Add key context: decisions, pending tasks, important details
- Write back to memory file
-
Alert user:
Say: "⚠️ Approaching context limit (~160k tokens). Saving checkpoint to memory before continuing."
-
Ask user:
- Continue and accept compaction?
- Summarize and restart fresh?
- Pause until ready?
What to Save
Essential information that must survive compaction:
- Decisions made in this conversation
- Pending tasks not yet completed
- Important context (project state, configurations, preferences)
- Files modified and their paths
- Unresolved issues requiring follow-up
When to Trigger
- At session start
- After every 30k tokens of conversation
- Before initiating large tasks (file edits, multiple operations)
- When user asks "how much context do we have left?"
Memory File Format
# YYYY-MM-DD
## Session Checkpoint (at X% context)
### Decisions
- Decision 1
- Decision 2
### Pending
- [ ] Task 1
- [ ] Task 2
### Important Context
- Project state: ...
- Last file modified: ...
### Unresolved
- Issue needing follow-up
