session-hygiene_skill

Overview

This skill prevents sessions.json from growing unbounded by archiving isolated sessions and rotating old archives. It sets up a cron-driven process that moves stale sessions into daily JSONL files, deletes archives older than a retention window, and keeps the live sessions.json lean and performant. Use it to avoid gateway slowdowns or as preventive maintenance on OpenClaw instances with hooks, crons, or subagents.

How this skill works

A scheduled job or manual script scans sessions.json for isolated sessions older than a configurable age and writes each session as one JSON line into a dated archive file (sessions-archive/YYYY-MM-DD.jsonl). Archived sessions are removed from sessions.json except for protected entries (e.g., agent:main:main). Archive files older than the retention period are deleted. The script reports counts and sizes and supports dry-run and tuning options.

When to use it

• When sessions.json grows large and gateway responses slow or time out
• On instances with frequent hooks, crons, or subagent runs that create many short-lived sessions
• As preventive maintenance to limit disk and memory usage from session bloat
• When you want a compact, searchable archive of historical sessions for audits or debugging
• Before backups or migrations to reduce dataset size

Best practices

• Schedule the cron to run at sensible intervals (every 6 hours recommended) and align timezone with your operational region
• Keep default protect rules for core agents and add additional protects if you rely on long-lived sessions
• Start with a dry-run to preview what will be archived before enabling destructive cleanup
• Tune --max-age-hours and --archive-retention-days to your traffic pattern—shorter retention for high-volume systems
• Monitor archive size and job logs to ensure rotation and deletion are working as expected

Example use cases

• Automate cleanup on an instance that receives many webhook-triggered sessions to prevent gateway lag
• Run a one-off aggressive purge when sessions.json is already causing slow startup or API timeouts
• Maintain a 30-day searchable history of isolated sessions for incident investigations without retaining everything in memory
• Integrate the cleanup cron with notifications (Slack/email) to report archived counts and any errors