Session Janitor

Session Janitor

Automated transcript and session hygiene for OpenClaw gateways.

What It Does

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:

| Key | Default | Description | |-----|---------|-------------| | trimMaxKB | 250 | Trim transcripts larger than this. Trim always fires when exceeded — there is no minimum pair count. | | keepPairs | 10 | Number of recent user/assistant pairs to keep after trim. If fewer pairs exist than this, all are kept (no skip). | | keepFullPairs | 2 | Most recent N assistant turns that keep full toolResult bodies (older turns are collapsed to summary lines) | | minArchivePairs | 5 | Informational only — no longer blocks trim. Sessions exceeding trimMaxKB are always trimmed. | | trimFullThresholdPct | 50 | Two-stage aggressive reduction when trimmed output still exceeds this % of trimMaxKB: (1) strip all assistant turns (tool args + thinking removed); (2) if still over threshold, drop all toolResult entries entirely. Set to 100 to disable. | | archiveRetentionDays | 7 | Delete old archives after this many days (applies to .reset.*, .deleted.*, .pre-trim.*, .bak-*, .purged.*, .emergency-*) | | keepPreTrimFiles | 3 | Max .pre-trim.* files to keep per session (oldest deleted immediately, regardless of retention period) | | orphanGraceMinutes | 30 | Wait before archiving orphan transcripts | | staleSubagentHours | 24 | Prune subagent session entries older than this | | staleCronSessionHours | 24 | Prune cron session entries older than this | | llmExtraction.enabled | true | Use LLM to extract memories from trimmed content | | llmExtraction.model | openclaw | Model identifier to use for extraction calls | | llmExtraction.maxInputChars | 20000 | Max characters of archived content sent to LLM | | llmExtraction.timeoutSecs | 60 | LLM API call timeout in seconds | | llmExtraction.maxMemories | 15 | Max memories to accept from a single LLM extraction | | llmExtraction.minArchived | 3 | Minimum archived messages required before running LLM extraction | | llmExtraction.maxPerRun | 1 | Max LLM extractions per cron cycle (cost control) | | memCli.enabled | false | Store extracted memories via mem CLI (requires mem) | | cronSchedule | */15 * * * * | How often to run | | sidecar.enabled | true | Offload large toolResult entries to .toolcache/ files | | sidecar.minEntryBytes | 5120 | Minimum toolResult content size (bytes) to trigger offload | | extractOnTrim.enabled | false | Fire async LLM memory extraction after each watcher-triggered trim | | extractOnTrim.minArchivedPairs | 3 | Minimum archived message pairs required before running extraction | | extractOnTrim.scene | auto | Memory scene tag to use (auto lets the LLM infer from context) | | extractOnTrim.salience | 0.5 | Default salience for extracted memories (0.1–1.0) | | watchdog.enabled | false | Run hung-session detector after each janitor pass | | watchdog.staleMinutes | 5 | Session updatedAt age threshold to consider stuck | | watchdog.alertSlack | true | Send Slack DM when a stuck session is detected | | watchdog.slackTarget | — | Slack user ID or channel to notify | | watchdog.autoRestart | false | Auto-trigger safe-restart script on detection (use with caution) | | watchdog.restartScriptSlack | ~/bin/safe-slack-restart.sh | Safe restart script path for Slack gateway | | watchdog.restartScriptDiscord | ~/bin/safe-gateway-restart.sh | Safe restart script path for Discord gateway |

Gateway Discovery

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

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

LLM Extraction Guardrails

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

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

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

Edit config.json after setup to tune thresholds:

| Key | Default | Description | |-----|---------|-------------| | trimMaxKB | 250 | Trim transcripts larger than this. Trim always fires when exceeded — there is no minimum pair count. | | keepPairs | 10 | Number of recent user/assistant pairs to keep after trim. If fewer pairs exist than this, all are kept (no skip). | | keepFullPairs | 2 | Most recent N assistant turns that keep full toolResult bodies (older turns are collapsed to summary lines) | | minArchivePairs | 5 | Informational only — no longer blocks trim. Sessions exceeding trimMaxKB are always trimmed. | | trimFullThresholdPct | 50 | Two-stage aggressive reduction when trimmed output still exceeds this % of trimMaxKB: (1) strip all assistant turns (tool args + thinking removed); (2) if still over threshold, drop all toolResult entries entirely. Set to 100 to disable. | | archiveRetentionDays | 7 | Delete old archives after this many days (applies to .reset.*, .deleted.*, .pre-trim.*, .bak-*, .purged.*, .emergency-*) | | keepPreTrimFiles | 3 | Max .pre-trim.* files to keep per session (oldest deleted immediately, regardless of retention period) | | orphanGraceMinutes | 30 | Wait before archiving orphan transcripts | | staleSubagentHours | 24 | Prune subagent session entries older than this | | staleCronSessionHours | 24 | Prune cron session entries older than this | | llmExtraction.enabled | true | Use LLM to extract memories from trimmed content | | llmExtraction.model | openclaw | Model identifier to use for extraction calls | | llmExtraction.maxInputChars | 20000 | Max characters of archived content sent to LLM | | llmExtraction.timeoutSecs | 60 | LLM API call timeout in seconds | | llmExtraction.maxMemories | 15 | Max memories to accept from a single LLM extraction | | llmExtraction.minArchived | 3 | Minimum archived messages required before running LLM extraction | | llmExtraction.maxPerRun | 1 | Max LLM extractions per cron cycle (cost control) | | memCli.enabled | false | Store extracted memories via mem CLI (requires mem) | | cronSchedule | */15 * * * * | How often to run | | sidecar.enabled | true | Offload large toolResult entries to .toolcache/ files | | sidecar.minEntryBytes | 5120 | Minimum toolResult content size (bytes) to trigger offload | | extractOnTrim.enabled | false | Fire async LLM memory extraction after each watcher-triggered trim | | extractOnTrim.minArchivedPairs | 3 | Minimum archived message pairs required before running extraction | | extractOnTrim.scene | auto | Memory scene tag to use (auto lets the LLM infer from context) | | extractOnTrim.salience | 0.5 | Default salience for extracted memories (0.1–1.0) | | watchdog.enabled | false | Run hung-session detector after each janitor pass | | watchdog.staleMinutes | 5 | Session updatedAt age threshold to consider stuck | | watchdog.alertSlack | true | Send Slack DM when a stuck session is detected | | watchdog.slackTarget | — | Slack user ID or channel to notify | | watchdog.autoRestart | false | Auto-trigger safe-restart script on detection (use with caution) | | watchdog.restartScriptSlack | ~/bin/safe-slack-restart.sh | Safe restart script path for Slack gateway | | watchdog.restartScriptDiscord | ~/bin/safe-gateway-restart.sh | Safe restart script path for Discord gateway |