Maintain peak performance by automatically archiving stale session data and preventing database bloat in your AI agent environment.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install session-hygiene
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install session-hygiene using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Session Hygiene?
Session Hygiene is a specialized maintenance utility designed to solve the problem of unbounded session growth within the OpenClaw architecture. In high-activity environments where hooks, crons, and subagents are frequently triggered, the primary session store can quickly swell to hundreds of megabytes, leading to significant gateway latency or complete unresponsiveness.
This skill provides a robust solution within the ecosystem of Openclaw Skills by implementing an automated archive-and-rotate workflow. It ensures that your active session file remains small and performant while safely moving historical data into organized daily logs. By integrating this skill, developers can prevent the performance degradation that typically occurs when session counts exceed several thousand entries.
Session Hygiene Use Cases
- Preventing performance degradation in instances with high-frequency webhook or cron activity.
- Automating the removal of isolated subagent sessions that are no longer needed for active operations.
- Maintaining historical session data for compliance or debugging without slowing down the live agent gateway.
- Managing disk space on self-hosted deployments through automated archive rotation.
How Session Hygiene Works
- The skill triggers a Python-based cleanup script via a scheduled cron job or manual command.
- It scans the sessions.json file to identify sessions older than a configurable threshold, typically 48 hours.
- It filters out protected entries, such as the main agent session, to ensure core system stability.
- Identified stale sessions are extracted and appended to daily archive files in JSONL format.
- The script prunes the original session store, significantly reducing file size and memory overhead.
- Finally, it rotates the archives by deleting files older than a specified retention period, such as 30 days.
Session Hygiene Setup
To deploy this as a background task, execute the following JavaScript command within your agent to establish a recurring 6-hour maintenance cycle:
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" }
})
For immediate cleanup if your instance is already experiencing lag, run the script manually via the CLI:
python3 <skill-dir>/scripts/archive_sessions.py --max-age-hours 48
Session Hygiene Data Schema & Taxonomy
The skill manages data across active and archival storage to balance performance and history. Like many Openclaw Skills, it prioritizes clear file structures.
| Location | Format | Purpose |
|---|---|---|
| sessions.json | JSON | The active session store used by the gateway for real-time operations. |
| sessions-archive/ | Directory | Storage location for all processed and rotated session data. |
| YYYY-MM-DD.jsonl | JSONL | Daily log files containing one archived session per line for high efficiency. |
| Protected Keys | String | Hardcoded identifiers like agent:main:main that are exempt from cleanup. |
Session Hygiene Advanced Features
- Dry-run capability using the --dry-run flag to simulate cleanup and estimate space savings without modifying files.
- Configurable session age thresholds allowing for aggressive purging or longer retention based on specific needs.
- Automatic path detection for seamless integration into various Openclaw Skills installation environments.
- Detailed reporting logs that provide visibility into the number of sessions archived and the resulting file size reductions.
SKILL.md
Loading
Related Openclaw Skills
duely
A lightweight command-line utility for scheduling, tracking, and logging recurring maintenance tasks and periodic chores.
calmly
A silent macOS command-line tool for managing Calendar events via EventKit, bypassing slow AppleScript and UI prompts.
Klaw Arena
Klaw Arena is an autonomous, agent-first RPG where AI klaws farm gold, engage in strategic arena combat, and progress through a competitive ranking system.
UA1 Validator Agent
A specialized agent skill for running deterministic PDF/UA-1 accessibility checks and remediation loops via the ua1.dev API.
timely
A command-line interface for Apple Reminders that supports natural language dates and location-based geofencing triggers.
Complex Task Three-Step Methodology
A sophisticated three-step framework designed to guide AI agents through zero-cost screening, lightweight assessment, and deep DAG-based planning for complex task execution.
Featured*
