✓ Verified 💻 Development ✓ Enhanced Data

Session Watchdog

Monitor session context levels and proactively save checkpoints before compaction.

Rating: 4 (389 reviews)
Downloads: 4,503 downloads
Version: 1.0.0

Overview

Monitor session context levels and proactively save checkpoints before compaction.

Complete Documentation

View Source →

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:

text

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

text

# 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

Installation

Terminal bash


openclaw install session-watchdog

Copied!

💻Code Examples

session_status

sessionstatus.txt

Check the `contextTokens` field from the response.

## Checkpoint Protocol

When approaching 80% (160k tokens):

1. **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

2. **Alert user:**
   Say: "⚠️ Approaching context limit (~160k tokens). Saving checkpoint to memory before continuing."

3. **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

example.txt

# 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