Context Compression — 技能工具

--- 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. ```bash # 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` ```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](https://docs.openclaw.ai)