Session Hygiene

Prevent sessions.json bloat from accumulating isolated sessions (hooks, crons, subagents). Sets up a cron to archive stale sessions to daily JSONL files and...

Security Scan

The skill's files and instructions match its stated purpose (archiving and rotating OpenClaw sessions.json); it has no network calls, no extra env/credentials, and no install steps, so its footprint is coherent and proportional.

Purpose & Capability

Name/description match the contents: the SKILL.md explains cron setup and the included Python script archives stale sessions and rotates old archives. There are no unrelated requirements (no external credentials, no unrelated binaries).

Instruction Scope

Runtime instructions are scoped to locating sessions.json, writing per-day JSONL archives into sessions-archive, deleting old archives, and updating sessions.json. The SKILL.md does not ask the agent to read or transmit unrelated files or secrets. It instructs running the included script via a cron payload or manually; that's consistent.

Install Mechanism

No install spec or external downloads. The skill is instruction-only plus a small local Python script; nothing is fetched from remote URLs and no archives are extracted.

Credentials

No environment variables, credentials, or config paths are requested. The script auto-detects common sessions.json locations under the user's home directory (or accepts an explicit --sessions-path). This access is proportional to the stated task.

Persistence & Privilege

Does not request always:true, does not modify other skills or system-wide agent settings. It writes only to the sessions directory (sessions.json and sessions-archive) which is the minimal required privilege for its function.

Assessment

This skill appears to do what it says, but take normal precautions before running it: (1) run with --dry-run first to preview actions; (2) back up sessions.json (or run the script against a copy) before writing to it; (3) ensure the cron runs as the same user that owns sessions.json so auto-detection succeeds and there are no permission issues; (4) if your sessions.json is located outside the auto-detected paths, provide --sessions-path explicitly; (5) be aware the script loads sessions.json into memory (very large files could use significant RAM); and (6) inspect the archive files and test on a non-production instance if possible. These are operational cautions, not indicators of malicious behavior.

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:

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):

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

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

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

Sessions/day	48h retention	sessions.json size
50	~100 sessions	~3MB
100	~200 sessions	~6MB
200	~400 sessions	~12MB

Without this skill, the same setup would grow to 200MB+ within a month.