session-hygiene

# Session Hygiene

OpenClaw's session store (`sessions.json`) grows unbounded — every hook, cron, and subagent invocation creates a session entry that never gets cleaned up. Heavy setups (webhooks + crons) can hit 200MB+ and 7000+ sessions within weeks, causing gateway slowdowns and unresponsiveness.

This skill sets up automated archive-and-rotate to keep `sessions.json` lean while preserving session history.

## Quick Setup

Create a cron that runs every 6 hours:

```javascript
cron(action: "add", job: {
  name: "Session Archive & Cleanup",
  schedule: { kind: "cron", expr: "0 */6 * * *", tz: "America/Los_Angeles" },
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "Archive and clean up stale sessions. Run the script: python3 <skill-dir>/scripts/archive_sessions.py",
    timeoutSeconds: 60
  },
  delivery: { mode: "announce", channel: "slack" }
})
```

Adjust the timezone and delivery channel to match your setup.

## What It Does

1. **Archive**: Sessions older than 48 hours get moved to `sessions-archive/YYYY-MM-DD.jsonl` (one JSON line per session, grouped by date)
2. **Protect**: `agent:main:main` is never removed
3. **Rotate**: Archive files older than 30 days are deleted
4. **Report**: Logs how many sessions were archived, how many remain, and file sizes

## Manual Run

For an immediate cleanup (e.g., if sessions.json is already bloated):

```bash
python3 <skill-dir>/scripts/archive_sessions.py
```

Or for a one-time aggressive purge of sessions older than N hours:

```bash
python3 <skill-dir>/scripts/archive_sessions.py --max-age-hours 1
```

## Tuning

| Parameter | Default | Notes |
|-----------|---------|-------|
| `--max-age-hours` | 48 | How old a session must be before archiving |
| `--archive-retention-days` | 30 | How long to keep archive JSONL files |
| `--sessions-path` | Auto-detected | Path to sessions.json |
| `--dry-run` | off | Preview what would be archived without changing anything |

## Sizing Estimates

| Sessi...