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 .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

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"
  ]
}

Troubleshooting

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