Context Compression

Prevent context overflow with automatic session truncation and memory preservation.

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 .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 memory/YYYY-MM-DD.md
• 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
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.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
• maxChars: 40000 — keeps substantial history per session
• strategy: priority-first — 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