Compress Session Context Prevent Overflow

---
name: compress-session-context-prevent-overflow
description: "Prevent context overflow with automatic session truncation and memory preservation."
category: "Community"
author: community
version: "3.13.3"
icon: puzzle
---

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