Context Compactor

Compresses long conversations into structured summaries. Saves token by replacing raw conversation history with dense, searchable digests.

Requirements

• Runtime: Python 3.10+ (standard library only)
• OS: Linux, macOS
• Environment variables:
  • OPENCLAW_WORKSPACE — Workspace root (default: ~/.openclaw/workspace)
• Environment: OPENCLAW_WORKSPACE (default: ~/.openclaw/workspace)

Security

Write Restrictions (Hard Rules)

The agent may ONLY write to these locations:

• memory/compacts/ — compact files only
• SESSION-STATE.md — via smart-memory skill (not this skill)

The agent MUST NOT write to:

• Any directory outside the workspace
• System directories (/etc, /usr, /var, /tmp except session cache)
• User home directory root (~/.ssh, ~/.config, ~/.aws, etc.)
• Any .* dotfile or dotdir in workspace root
• Any file not matching memory/compacts/*.md

Read Restrictions

The agent may ONLY read from:

• The current conversation context (already available)
• memory/compacts/ — for listing/reading past compacts

The agent MUST NOT read from:

• /etc/passwd, /etc/shadow, or any system credential file
• ~/.ssh/, ~/.aws/, ~/.config/openclaw/ or similar
• Any file outside the workspace unless explicitly asked by the user

Redaction Enforcement

Before writing ANY compact, the agent MUST run this checklist:

1. ✅ No file paths (replace with <REDACTED_PATH>)
2. ✅ No URLs (replace with <REDACTED_URL>)
3. ✅ No internal IPs (replace with <INTERNAL_URL>)
4. ✅ No passwords, tokens, API keys (delete entirely)
5. ✅ No personal info beyond work context

If any item fails → do not write the compact until fixed.

Privacy Boundaries

What Compacts May Contain

• Decisions, facts, pending actions, blockers
• Project names and feature descriptions

What Compacts Must NOT Contain

• File system paths (use <REDACTED_PATH> placeholder)
• Internal URLs, endpoints, or infrastructure details
• API keys, tokens, passwords, secrets (script-level regex filter)
• Private keys or certificates
• User personal information beyond work context

Agent Rules

• Before saving a compact, strip or redact all paths, internal URLs, and credentials
• Use placeholders: <PROJECT_ROOT>, <INTERNAL_URL>, <DB_CONFIG>
• If unsure whether something is sensitive, redact it
• Compacts are for "what was decided" not "where things live"

Data Isolation

• Keyword extraction: Fully local — no network calls, no external transmission
• LLM extraction (opt-in): Sends conversation text to the agent's configured LLM provider. This is inherent to using any LLM-based compaction and is not controlled by this skill. The skill only provides the prompt template; the agent/platform handles the actual API call.
• Maximum 30 compacts retained, oldest auto-deleted
• Compacts are stored locally and read locally — the skill itself never makes network calls

How It Works

Long conversation (10,000+ tokens)
    ↓
compact_session.py --extract
    ↓
Structured digest (~500 tokens)
    ↓
Saved to memory/compacts/YYYY-MM-DD-HHMM.md
    ↓
New session reads latest compact on startup

Compression ratio: ~20:1 — a 10,000 token conversation becomes ~500 token digest.

Quick Reference

How compaction works: The agent drafts the compact content, then pipes it through --write which enforces security checks (no paths, URLs, IPs, secrets) before saving. This ensures programmatic enforcement — the agent never writes directly to disk.

Compact Format

# Session Compact — 2026-03-31 17:00 UTC
**Turns**: 45 | **Est. tokens saved**: ~9,500

## Decisions Made
- [2026-03-31] Chose SQLite over Redis for golden3 prompts
- [2026-03-31] Decided to use zero-dependency approach for smart-memory

## Facts Established
- [PROJ] golden3 site at golden3.killclaw.xyz, repo github.com/zgjq/golden3
- [TECH] Prompts stored in data/golden3.db, table `prompts`, category `scoring`
- [PREF] User prefers direct, no-nonsense communication style

## Pending Actions
- [ ] Publish smart-memory to ClawHub
- [ ] Fix scoring display from 100-point to 10-point scale

## Technical Context
- Server: ubuntu-4gb-hel1-1, Node v24.14.0
- Golden3 uses node:sqlite (DatabaseSync)

## Blockers / Open Questions
- Need ClawHub login token to publish

## Session Summary
Built smart-memory skill from Claude Code architecture study. Published to ClawHub
as smart-memory-zero-dep. Memory system now active with WAL protocol, type
classification, temporal decay, and snapshot/restore.

Agent Behavior

When to Compact

• Conversation exceeds ~50 turns
• Context window approaching limits (see AGENTS.md token discipline rules)
• User says "compact", "summarize", "fresh start", "压缩"

How to Compact

The agent drafts the compact content, then saves it via:

echo "compact content" | python3 scripts/compact_session.py --write

The --write flag enforces all security checks programmatically: redaction of paths/URLs/IPs/secrets, path containment within workspace, and file naming. The agent NEVER writes directly to disk.

When to Inject Compact

• New session startup — check for recent compact
• User asks "what were we working on"
• Context search returns nothing but a compact exists

Extraction Rules

From the conversation, extract:

1. Decisions — anything with "chose X over Y", "decided to", "going with"
2. Facts — URLs, file paths, configs, technical details, user preferences
3. Pending — uncompleted tasks, "later", "TODO", "next step"
4. Blockers — "need X first", "blocked by", "waiting for"
5. Summary — 2-3 sentence overview of what happened

Skip:

• Greetings, small talk, "ok", "嗯"
• Repeated information already in MEMORY.md
• Debugging noise (unless it led to a LESSON)
• Sensitive data (tokens, passwords)

Integration with smart-memory

This skill works with smart-memory:

• Compacts reference [TYPE] tags from smart-memory's classification system
• Pending items from compacts can feed into wal pending
• Facts from compacts can be promoted to MEMORY.md
• Compacts live in memory/compacts/ — decayed by smart-memory's archival system

File Structure

~/.openclaw/workspace/
├── memory/
│   └── compacts/
│       ├── 2026-03-31-1700.md   # Session compact
│       ├── 2026-03-30-1430.md
│       └── ...