🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Context Compression
🦀 ClawHub

Context Compression

by @lifei68801

Prevent context overflow with automatic session truncation and memory preservation.

Versionv3.13.3
Downloads2,408
Installs27
Stars⭐ 4
#clawhub
TERMINAL
clawhub install context-compression

📖 About This Skill

name: context-compression version: 3.13.3 description: "Prevent context overflow with automatic session truncation and memory preservation." license: MIT-0 author: lifei68801 metadata: openclaw: requires: bins: ["bash", "jq", "sed", "grep", "head", "tail", "wc", "date", "tr", "cut"] configPaths: - "~/.openclaw/workspace/.context-compression-config.json" - "~/.openclaw/workspace/MEMORY.md" - "~/.openclaw/agents/*/sessions/*.jsonl" - "~/.openclaw/workspace/memory/" permissions: - "file:read:~/.openclaw/agents/main/sessions/*.jsonl" - "file:write:~/.openclaw/agents/main/sessions/*.jsonl" - "file:read:~/.openclaw/workspace/memory/*.md" - "file:read:~/.openclaw/workspace/MEMORY.md" - "file:write:~/.openclaw/workspace/memory/*.md" - "file:write:~/.openclaw/workspace/MEMORY.md" - "file:write:~/.openclaw/workspace/.context-compression-config.json" installDir: "~/.openclaw/workspace/skills/context-compression" fileLayout: "SKILL.md": "This file" "configure.sh": "Interactive setup wizard" "truncate-sessions-safe.sh": "Core session trimming" "identify-facts.sh": "Keyword-based fact detection" "identify-facts-enhanced.sh": "AI-assisted fact detection (calls local openclaw CLI)" "check-preferences-expiry.sh": "Remove expired preferences" "session-start-hook.sh": "Session-start context loader" "session-end-hook.sh": "Session-end context saver" "check-context-health.sh": "Context status reporter" "check-context.sh": "Lightweight context check" "content-priority.sh": "Content priority scoring" "generate-daily-summary.sh": "Daily summary from notes" "generate-smart-summary.sh": "Smart summary generation" "mid-session-check.sh": "Mid-session keyword scanner" "pre-session-check.sh": "Pre-session context check" "time-decay-truncate.sh": "Time-decay based truncation" "auto-identify-on-session.sh": "Auto fact identification on session" behavior: modifiesLocalFiles: true network: local telemetry: none credentials: none settings: "~/.openclaw/workspace/.context-compression-config.json" description: "Reads and trims local session files. Writes identified facts to MEMORY.md and daily notes. The optional AI-assisted fact identification invokes the local openclaw agent CLI (network depends on user's OpenClaw config). No scripts make external HTTP calls directly."

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

    | 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

    • 💡 Examples

    > 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

    ⚙️ 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 |

    📋 Tips & Best Practices

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