Smart Context Manager

AI-powered context management for OpenClaw sessions

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (summarize and compress OpenClaw sessions); it reads and manipulates local session files and uses the OpenClaw CLI as expected.

Purpose & Capability

The name/description (context management) match the included script and SKILL.md. The script requires and uses the OpenClaw CLI, jq, and access to the OpenClaw state directory (~/.openclaw or OPENCLAW_STATE_DIR) — all appropriate for reading, backing up, resetting, and reinjecting session context.

Instruction Scope

Instructions and the script perform exactly what they claim: request a summary from the agent, back up the JSONL session, delete the session file to reset, and inject the summary. This is potentially destructive when run with --replace; the skill documents backups and the behavior, but users should be aware that full session contents are read, written to memory/compressed/, and (on replace) the original JSONL is deleted.

Install Mechanism

No install spec; it's an instruction-only skill with a shell script. Nothing is downloaded from external URLs or installed automatically by the skill itself.

Credentials

The skill requests no environment variables or credentials. It optionally uses OPENCLAW_STATE_DIR to locate session files (falls back to ~/.openclaw) — this is proportional and required for its function.

Persistence & Privilege

always is false and the skill does not request permanent platform-wide privileges. It modifies session files under the OpenClaw state directory (its intended scope) and writes backups into its own memory/compressed directory.

Assessment

This skill is internally consistent with its stated purpose, but be aware of these practical risks before installing: 1) The summarize+--replace operation is destructive: it deletes the session JSONL after backing it up — test with the read-only summarize command first. 2) Backups and generated summaries are stored in the skill's memory/compressed/ folder and may contain sensitive conversation data; check file permissions and retention. 3) Summarization is performed by your agent (and thus its configured model/provider), so session contents will be sent to whatever LLM backend your agent uses — ensure that is acceptable for any sensitive data. 4) The script requires the openclaw CLI and jq and read/write access to your OpenClaw state directory (~/.openclaw); review the script (compress.sh) yourself before running and keep a manual copy of important sessions if you need stronger guarantees.

Context Manager Skill

AI-powered context management for OpenClaw sessions. Uses the agent itself to generate intelligent summaries, then resets the session with compressed context.

Quick Start

# List all sessions with usage stats
~/openclaw/skills/context-manager/compress.sh list

# Check status of a specific session
~/openclaw/skills/context-manager/compress.sh status agent:main:main

# Generate AI summary (read-only, safe)
~/openclaw/skills/context-manager/compress.sh summarize agent:main:main

# Compress session: generate summary, reset, inject (DESTRUCTIVE)
~/openclaw/skills/context-manager/compress.sh summarize agent:main:main --replace

When to Use

• Context usage approaching 70-80%+
• Long sessions with extensive conversation history
• Before the session becomes slow or loses coherence
• Proactively to maintain fast, focused sessions

How It Works

1. AI Summarization: Sends a prompt to the agent asking it to summarize its own context
2. Backup: Saves the original JSONL session file to memory/compressed/
3. Reset: Deletes the JSONL file (official reset method)
4. Inject: Sends the AI-generated summary as the first message in the fresh session
5. Result: Same session key, new session ID, compressed context

Key insight: The agent has full visibility into its own context, so it generates the best possible summary.

Commands

Session Commands

Command	Description
list	List all sessions with token usage
status [KEY]	Show detailed status for a session
summarize [KEY]	Generate AI summary (read-only)
summarize [KEY] --replace	Summarize AND reset session with compressed context
compress [KEY]	Legacy grep-based extraction (not recommended)
check [KEY]	Check if session exceeds threshold
check-all	Check all sessions at once

Configuration Commands

Command	Description
set-threshold N	Set compression threshold (50-99%, default: 80)
set-depth LEVEL	Set depth: brief/balanced/comprehensive
set-quiet-hours HH	Set quiet hours (e.g., "23:00-07:00")
help	Show help and usage examples

Examples

List All Sessions

$ ~/openclaw/skills/context-manager/compress.sh list
📋 Available Sessions (4 total)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#    SESSION KEY                              KIND       TOKENS    USAGE
1    agent:main:main                          direct      70188      70%
2    agent:main:slack:channel:c0aaruq2en9     group       20854      20%
3    agent:main:cron:0d02af4b-...             direct      18718      18%

Check Session Status

$ ~/openclaw/skills/context-manager/compress.sh status agent:main:main
📊 Context Manager Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Session Key: agent:main:main
  Session ID:  fc192a2d-091c-48c7-9fad-12bf34687454
  Kind:        direct
  Model:       gemini-3-flash
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Threshold:   80%
  Tokens:      70188 / 100000
  Usage:       70%

Generate AI Summary (Safe, Read-Only)

$ ~/openclaw/skills/context-manager/compress.sh summarize agent:main:main
🧠 Requesting AI summary for session: agent:main:main
  Session ID: fc192a2d-091c-48c7-9fad-12bf34687454

✅ AI Summary generated!
  Saved to: memory/compressed/20260127-123146.ai-summary.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
### Session Summary: January 27, 2026

#### 1. What was accomplished
- System audit completed
- Essay generation with sub-agents
...

Full Compression (Summarize + Reset + Inject)

$ ~/openclaw/skills/context-manager/compress.sh summarize agent:main:main --replace
🧠 Requesting AI summary for session: agent:main:main
  Session ID: fc192a2d-091c-48c7-9fad-12bf34687454
  Mode: REPLACE (will reset session after summary)

✅ AI Summary generated!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[AI-generated summary displayed]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Resetting session and injecting compressed context...
  Backing up session file...
  Backup saved: memory/compressed/20260127-123146.session-backup.jsonl
  Deleting session JSONL to reset...
  Injecting compressed context into fresh session...
✅ Session compressed successfully!
  Old session ID: fc192a2d-091c-48c7-9fad-12bf34687454
  New session ID: a1b2c3d4-...
  Session is ready to continue with compressed context

Result: 70k tokens → 16k tokens (77% reduction)

Output Files

When compression occurs, these files are created in memory/compressed/:

File	Description
{timestamp}.ai-summary.md	AI-generated session summary
{timestamp}.session-backup.jsonl	Full backup of original session (can restore if needed)
{timestamp}.transcript.md	Raw transcript extraction (legacy)
{timestamp}.summary.md	Grep-based summary (legacy)

Requirements

• openclaw - Gateway must be running
• jq - JSON parsing (brew install jq)
• Gateway access - Script uses openclaw agent and openclaw sessions

Technical Details

Session Reset Method

The script uses JSONL deletion to reset sessions (official method):

1. Backup JSONL to memory/compressed/
2. Delete ~/.openclaw/agents/{agent}/sessions/{sessionId}.jsonl
3. Send compressed context via openclaw agent --to main
4. New session is created automatically with summary as first message

Why Not /reset?

The /reset slash command only works in the chat interface. When sent via openclaw agent --session-id, it's treated as a regular message and the agent tries to interpret it as a task.

AI Summarization Prompt

The script asks the agent to provide:

1. What was accomplished (key tasks)
2. Key decisions made (with rationale)
3. Current state (where we left off)
4. Pending tasks (what still needs doing)
5. Important context (critical info to remember)

Troubleshooting

Summary Text Empty

If the AI summary extraction fails, check stderr redirect:

# The script uses 2>/dev/null to avoid Node deprecation warnings breaking JSON
openclaw agent --session-id $ID -m "..." --json 2>/dev/null

Session Not Resetting

Verify the JSONL file path:

ls ~/.openclaw/agents/main/sessions/

Restore From Backup

If something goes wrong:

cp memory/compressed/{timestamp}.session-backup.jsonl \
   ~/.openclaw/agents/main/sessions/{sessionId}.jsonl

Check Logs

Use openclaw logs to troubleshoot:

openclaw logs --limit 50 --json | grep -i "error\|fail"

Best Practices

1. Backup first: The script auto-backs up, but you can also manually backup before testing
2. Test on non-critical sessions first: Try on a Slack channel or cron session before main
3. Check the summary: Run summarize without --replace first to verify the summary quality
4. Monitor token count: Use status to verify compression worked

See Also

• openclaw sessions --help
• openclaw agent --help