Session Janitor

Automated transcript and session hygiene for OpenClaw gateways.

What It Does

• Sidecar offloader — extracts large tool outputs (≥5KB) to .toolcache/ files, replacing inline content with lightweight stubs. Runs before trim on every turn.
• Trims oversized transcripts — keeps recent exchanges + synthetic compaction summary, archives the rest
• LLM memory extraction — uses the gateway's chat completions API to extract structured memories (facts, decisions, lessons) from trimmed content before discarding
• Prunes stale sessions — removes old subagent/cron session entries from sessions.json
• Archives orphan transcripts — files with no active session after a grace period
• Cleans old archives — removes pre-trim, reset, and checkpoint files after retention period
• Cleans orphaned checkpoints — removes .checkpoint..jsonl files left behind by auto-compaction once the parent session no longer has an active transcript

Setup

bash skills/session-janitor/scripts/setup.sh

Setup auto-discovers all gateway installations (~/.openclaw/, ~/.openclaw-*/), generates config.json, installs a cron job, and installs the watcher service (systemd on Linux, launchd on macOS).

macOS Prerequisites

Install fswatch for the per-turn watcher:

brew install fswatch

The cron-based janitor works without it (trimming every 15 min instead of within ~3s of each turn).

For architecture details, trimming mechanics, and token math, see ARCHITECTURE.md.

Configuration

Edit config.json after setup to tune thresholds:

Gateway Discovery

Setup scans for ~/.openclaw/openclaw.json and ~/.openclaw-*/openclaw.json. Each discovered gateway gets its own entry in config.json with:

• Port (from gateway.port in config)
• Auth token (from gateway.auth.token)
• Sessions directory path

Works with single-gateway installs, multi-gateway (Discord + Slack), or any custom layout.

LLM Extraction Guardrails

• Lockfile — only one extraction at a time across all gateways
• Max per run — configurable cap per cron cycle (default: 1)
• 20K char input cap — truncates middle of very long conversations
• 60s hard timeout — SIGALRM kills hung API calls
• Dedup — state file tracks processed trims, never re-runs
• No context inflation — memories go to mem DB only, never to files that get auto-loaded into session context

Manual Run

bash skills/session-janitor/scripts/janitor.sh

Logs

tail -f /tmp/session-janitor.log

Watcher Service

The watcher fires trim within ~3 seconds of each turn completing (vs. waiting for the next cron cycle). setup.sh installs it automatically as a system service.

Linux (systemd):

systemctl --user status session-janitor-watcher
systemctl --user restart session-janitor-watcher
tail -f /tmp/session-janitor-watcher.log

macOS (launchd):

launchctl list | grep session-janitor
launchctl unload ~/Library/LaunchAgents/ai.openclaw.session-janitor-watcher.plist
launchctl load  ~/Library/LaunchAgents/ai.openclaw.session-janitor-watcher.plist
tail -f /tmp/session-janitor-watcher.log

• Linux uses inotifywait (from inotify-tools) and watches via inotify kernel events.
• macOS uses fswatch (via Homebrew) and watches via FSEvents.

Watchdog

The watchdog runs after every janitor pass and checks updatedAt on all active sessions. If any session is stale longer than watchdog.staleMinutes, it fires a Slack alert. Optional autoRestart will trigger the appropriate safe-restart script.

Alert cooldown is 10 minutes per session to prevent spam. State is tracked in the janitor state file.

# Run standalone
bash skills/session-janitor/scripts/watchdog.sh 5 ~/.openclaw/session-janitor-state.json

Sub-Agent Reporting Conventions

Workers spawned via Foreman should use prefixed sessions_send messages to prevent the parent agent from spawning new sub-agents in response to status updates:

# Intermediate status (fire-and-forget — parent relays but does NOT spawn)
sessions_send(sessionKey="{PARENT}", message="STATUS: 🤖 [label]: doing X (60%)", timeoutSeconds=0)

# Errors/failures (normal delivery — parent may intervene)
sessions_send(sessionKey="{PARENT}", message="ERROR: 🤖 [label]: what failed — details")

# Completion (no prefix, normal delivery)
sessions_send(sessionKey="{PARENT}", message="🤖 [label]: ✅ done — summary")

• STATUS: → relay-only; timeoutSeconds=0 prevents reply-back loops
• ERROR: → parent receives and considers recovery action
• No prefix → completion; parent handles and relays to channel

Files

skills/session-janitor/
├── SKILL.md                              # This file
├── ARCHITECTURE.md                       # Deep dive: trimming mechanics, token math, examples
├── config.json                           # Generated by setup (gitignored)
├── config.example.json                   # Reference config
├── session-janitor-watcher.service       # Linux: systemd user service template
├── session-janitor-watcher.plist         # macOS: launchd LaunchAgent template
└── scripts/
    ├── setup.sh           # Discovery + config gen + cron + service install (Linux + macOS)
    ├── janitor.sh         # Main cron entry point
    ├── trim.py            # Transcript trimming (thinking, toolCall args, toolResult collapse)
    ├── sidecar.py         # Large toolResult offloader (→ .toolcache/ files)
    ├── watcher.sh         # Per-turn trigger (sidecar + trim; inotifywait/fswatch)
    ├── extract-llm.py     # LLM memory extraction
    ├── prune-sessions.py  # Stale session pruning
    ├── watchdog.sh        # Hung-session detector + Slack alert
    ├── test-sidecar.py    # Sidecar test suite (8 scenarios, 22 assertions)
    └── test-sidecar.sh    # Shell wrapper for sidecar tests