Session Guardian 🛡️

Never lose a conversation again.

  Without Guardian                    With Guardian
┌──────────────────┐            ┌──────────────────────────┐
│ Gateway crashes  │            │  Auto-backup every 5 min │
│ → conversation   │            │  Hourly snapshots        │
│   gone forever   │            │  Health monitoring       │
│                  │            │  One-command recovery    │
│ Token overflow   │            │                          │
│ → agent frozen   │            │  Gateway crash?          │
│                  │            │  → Restore in seconds    │
│ No way back. 😱  │            │                          │
└──────────────────┘            │  Token overflow?         │
                                │  → Auto-detected + alert │
                                │                          │
                                │  Always protected. 🛡️    │
                                └──────────────────────────┘

The Problem

Your OpenClaw conversations live in session files. When things go wrong — and they will — you lose everything:

🔴 Gateway restart → entire conversation history gone
🔴 Model disconnection → mid-task context wiped out
🔴 Token overflow → session too large, agent slows down or crashes
🔴 Disk issues → session files corrupted or lost

No built-in backup. No recovery. No warning before it's too late.

The Fix

clawhub install session-guardian
bash ~/.openclaw/workspace/skills/session-guardian/scripts/install.sh

That's it. Five layers of protection, running automatically.

How It Works

Layer 1: Incremental Backup    → Every 5 min   → New conversations saved
Layer 2: Hourly Snapshot       → Every hour     → Full session snapshots
Layer 3: Health Check          → Every 6 hours  → Detect problems early
Layer 4: Smart Summary         → Daily          → Key info extracted
Layer 5: Knowledge Extraction  → Daily          → Best practices saved

All automatic. All in the background. Zero manual work.

Quick Start

# Install
clawhub install session-guardian

# Deploy (sets up all cron jobs automatically)
cd ~/.openclaw/workspace/skills/session-guardian
bash scripts/install.sh

# Check status
bash scripts/status.sh

What You Get

✅ Auto-backup every 5 minutes — never lose more than 5 min of conversation
✅ Hourly snapshots — full point-in-time recovery
✅ Health monitoring — warns before token overflow crashes your agent
✅ One-command recovery — restore any session from any backup
✅ Multi-agent support — protects all your agents, not just main
✅ Collaboration tracking — see task flow across agents (King → Lead → Members)
✅ Knowledge extraction — auto-saves best practices from conversations
✅ Minimal overhead — ~10-15k tokens/day, ~1-2MB/agent/month

Usage

Check Status

bash ~/.openclaw/workspace/skills/session-guardian/scripts/status.sh

Shows: backup count, last backup time, snapshot count, cron jobs, disk usage.

Run Health Check

bash ~/.openclaw/workspace/skills/session-guardian/scripts/health-check.sh

Detects: oversized sessions, missing configs, disk space issues, gateway problems.

Restore a Session

# List available backups
bash ~/.openclaw/workspace/skills/session-guardian/scripts/restore.sh list

# Restore specific agent
bash ~/.openclaw/workspace/skills/session-guardian/scripts/restore.sh restore --agent main

View Collaboration Health (Multi-Agent)

bash ~/.openclaw/workspace/skills/session-guardian/scripts/collaboration-health.sh report

Track Task Flow

bash ~/.openclaw/workspace/skills/session-guardian/scripts/collaboration-tracker.sh trace "task name"

Cron Jobs (Auto-Configured)

After install.sh, these run automatically:

Schedule	Task	What it does
Every 5 min	Incremental backup	Save new conversations
Every hour	Snapshot	Full session archive
Every 6 hours	Health check	Detect problems
Daily 2am	Smart summary	Extract key info

File Structure

Assets/SessionBackups/
├── incremental/     # Every-5-min backups
├── hourly/          # Hourly snapshots
├── collaboration/   # Task flow records
└── Knowledge/       # Extracted best practices

All backups stay local. Nothing leaves your machine.

Who Is This For

Solo Agent User

✅ Protect your main conversation from crashes ✅ Get warned before token overflow kills your agent ✅ Recover in seconds, not hours of re-explaining

Multi-Agent Team

✅ Protect all agents (King + team leads + members) ✅ Track collaboration: who assigned what, who finished what ✅ Health scoring: monitor team communication quality ✅ Knowledge extraction: auto-save best practices from every agent

Troubleshooting

Problem	Fix
Backups not running	Check `crontab -l \| grep session-guardian`
Agent slow/timing out	Run health-check — likely token overflow
Can't restore	Run `restore.sh list` to see available backups
Disk filling up	Check config retention settings (default: 7 days incremental, 30 days snapshots)

Configuration

Edit scripts/config.sh to customize:

BACKUP_DIR         # Where backups go (default: Assets/SessionBackups)
INCREMENTAL_KEEP   # Days to keep incremental backups (default: 7)
SNAPSHOT_KEEP      # Days to keep snapshots (default: 30)
MAX_SESSION_SIZE   # Alert threshold for session size (default: 5MB)

Security

All data stays local — no external services, no network requests
No API keys required
Backups are excluded from git (add to .gitignore)
Does not modify your session files — only reads and copies

Performance

Operation	Tokens	Storage
Incremental backup	~100/run	~10KB/session/day
Hourly snapshot	~500/run	~100KB/session/day
Health check	~200/run	~2KB/report
Daily summary	~5k/run	~5KB/day
Total	~10-15k/day	~1-2MB/agent/month

Feedback

Star: clawhub star session-guardian
Update: clawhub update session-guardian

🇨🇳 中文说明