Context Compression
Keep conversations within limits. Never lose important context.
⚡ After installing, run the interactive setup wizard to generate your config file, then add the suggested cron entry with
crontab -e. See Quick Start below for commands.
Quick Start
File location: ClawHub installs this skill to
~/.openclaw/workspace/skills/context-compression/. All scripts are placed here directly. This is the standard OpenClaw skill install path — no manual file placement needed.
# 1. Install and configure (interactive)
bash ~/.openclaw/workspace/skills/context-compression/configure.sh
# 2. Verify config exists
cat ~/.openclaw/workspace/.context-compression-config.json
# 3. Set up crontab (example: every 10 minutes)
*/10 * * * * ~/.openclaw/workspace/skills/context-compression/truncate-sessions-safe.sh
How It Works
Session Truncation (truncate-sessions-safe.sh)
- Scheduling: System crontab (e.g.,
*/10 * * * *) - Action: Reads
.jsonlsession files under~/.openclaw/agents/*/sessions/, trims each file to the configured size - Safety: Skips files with a matching
.lockfile (active session) - Integrity: Keeps JSONL line boundaries intact — never splits a line
- Strategy:
priority-firstscans for important keywords before trimming and preserves matching lines
Fact Identification
- Keyword-based:
identify-facts.sh— scans truncated content for keywords (重要, 决定, TODO, 偏好, deadline, must remember, etc.) and appends findings tomemory/YYYY-MM-DD.md - AI-assisted:
identify-facts-enhanced.sh— callsopenclaw agent --agent main --messagewith the trimmed content to semantically identify important facts. Only used whenopenclawCLI is available on PATH. - Triggered by:
truncate-sessions-safe.shcalls one of these before each truncation cycle
Preference Lifecycle (check-preferences-expiry.sh)
- Scheduling: Once daily via crontab
- Mechanism: Reads MEMORY.md preference entries tagged with
@YYYY-MM-DD, removes expired ones - Tiers: Short-term (1-7 days), Mid-term (1-4 weeks), Long-term (permanent)
Scripts
| Script | Purpose | Scheduling |
|---|---|---|
truncate-sessions-safe.sh | Trim session JSONL files | crontab, every 10 min |
identify-facts.sh | Keyword-based fact detection | Called by truncate script |
identify-facts-enhanced.sh | AI-assisted fact detection | Called by truncate script |
check-preferences-expiry.sh | Remove expired preferences | crontab, once daily |
configure.sh | Interactive setup wizard | Manual, one-time |
session-start-hook.sh | Load context at session start | Called by AGENTS.md |
session-end-hook.sh | Save context at session end | Called by AGENTS.md |
check-context-health.sh | Report current context status | Manual / on-demand |
Configuration
File: ~/.openclaw/workspace/.context-compression-config.json
{
"version": "2.3",
"maxChars": 40000,
"frequencyMinutes": 10,
"skipActive": true,
"strategy": "priority-first",
"useAiIdentification": false,
"priorityKeywords": [
"重要", "决定", "记住", "TODO", "偏好",
"important", "remember", "must", "deadline"
]
}
| Field | Type | Default | Description |
|---|---|---|---|
| maxChars | number | 40000 | Max chars to keep per session file |
| frequencyMinutes | number | 10 | How often crontab runs truncate |
| skipActive | boolean | true | Skip sessions with .lock files |
| strategy | string | priority-first | Truncation strategy |
| useAiIdentification | boolean | false | Set true to use AI-assisted fact identification (may send content to remote LLMs) |
| priorityKeywords | string[] | (see above) | Keywords to preserve during truncation |
Troubleshooting
| Problem | Solution |
|---|---|
| Context still exceeded | Reduce maxChars in config |
| Memory not persisting | Check that AGENTS.md includes session-start-hook |
| Crontab not running | Verify PATH in crontab includes node/openclaw binary location |
Safety
Data Protection
- No deletion: Truncation writes the trimmed portion back to the same file. It does not delete files.
- Backup before trim:
truncate-sessions-safe.shcreates a.pre-trimbackup of each file before modification. Backups are cleaned up after a successful write. - Line integrity: Truncation only cuts at JSONL line boundaries. Partial lines are never written.
- Active sessions protected: Files with a matching
.lock(currently in use) are always skipped, even if oversized.
Safe Defaults
All configuration values have conservative defaults:
skipActive: true— never touches a running sessionmaxChars: 40000— keeps substantial history per sessionstrategy: priority-first— preserves lines matching priority keywords before trimming anything- No direct network access from scripts. The optional AI fact identification uses your local
openclawCLI — network activity depends on your OpenClaw configuration.
User Control
- Crontab: The user creates and manages all scheduled tasks. No script auto-installs crontab entries.
- Configuration: All settings live in a single JSON file. The
configure.shwizard runs interactively and requires user input. - Opt-out: Remove the crontab entry to stop all automated truncation. The skill has no background daemon of its own.
- Scope: Only reads/writes files under
~/.openclaw/agents/main/and~/.openclaw/workspace/memory/. Never touches system files, other agents' data, or other users' data.
Privacy Notice
- AI-assisted fact identification (
identify-facts-enhanced.sh) is disabled by default. It invokes the localopenclaw agentCLI, which may send session content to remote LLM services depending on your OpenClaw configuration. Only enable it if you understand and accept this data flow. To enable, set"useAiIdentification": truein the config file. - Keyword-based identification (
identify-facts.sh) is the default and runs entirely locally with no external data transmission. - Unattended cron execution: If you enable cron jobs, the scripts run without interactive consent. Review the scripts and test manually before enabling scheduled runs.