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.

CODEBLOCK0

---

How It Works

Session Truncation (truncate-sessions-safe.sh)

• - Scheduling: System crontab (e.g., */10 * * * *)
• Action: Reads .jsonl session files under ~/.openclaw/agents/*/sessions/, trims each file to the configured size
• Safety: Skips files with a matching .lock file (active session)
• Integrity: Keeps JSONL line boundaries intact — never splits a line
• Strategy: priority-first scans 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 to INLINECODE9
• AI-assisted: identify-facts-enhanced.sh — calls openclaw agent --agent main --message with the trimmed content to semantically identify important facts. Only used when openclaw CLI is available on PATH.
• Triggered by: truncate-sessions-safe.sh calls 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
INLINECODE16	Trim session JSONL files	crontab, every 10 min
INLINECODE17

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

CODEBLOCK1

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.sh creates a .pre-trim backup 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 session
• INLINECODE29 — keeps substantial history per session
• INLINECODE30 — preserves lines matching priority keywords before trimming anything
• No direct network access from scripts. The optional AI fact identification uses your local openclaw CLI — 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.sh wizard 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 local openclaw agent CLI, 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": true in 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.

---

Related

• - OpenClaw Documentation