Session Compact

OpenClaw Session Compact Plugin v1.2.1

Intelligent session compression plugin for OpenClaw that automatically manages token consumption and supports unlimited-length conversations. By automatically compressing historical messages into structured summaries, it significantly reduces token usage (typically 85-95% savings).

✨ New in v1.2.1

v1.1.0 Highlights

🚀 Quick Start

Installation

From ClawHub (recommended):

clawhub install openclaw-session-compact

Manual installation:

git clone https://github.com/SDC-creator/openclaw-session-compact.git \
  ~/.openclaw/extensions/openclaw-session-compact
cd ~/.openclaw/extensions/openclaw-session-compact
npm install --production

Configuration

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "allow": ["openclaw-session-compact"],
    "entries": {
      "openclaw-session-compact": {
        "enabled": true,
        "config": {
          "max_tokens": 10000,
          "preserve_recent": 4,
          "auto_compact": true,
          "model": ""
        }
      }
    }
  }
}

重要：配置参数从 OpenClaw 配置系统读取。修改配置后需要重启 Gateway：

openclaw gateway restart

💡 Usage Scenarios

Scenario 1: CLI Commands

# Check current session status
openclaw compact-status
Manually trigger compression
openclaw compact
Force compression (ignores threshold)
openclaw compact --force
View configuration
openclaw compact-config

Scenario 2: Automatic Compression

# Start OpenClaw - compression works automatically
openclaw start
When conversation history exceeds the threshold, it auto-compresses
and continues seamlessly without user intervention

Scenario 3: Long Conversation Handling

Problem: Conversations exceeding 10,000 tokens cause:

Solution: Session Compact automatically compresses history:

Before: 50 messages (1,250 tokens)
        ↓ [Auto-compress]
After:  5 messages (360 tokens) - 92% token savings

🔧 Configuration Options

| Parameter | Type | Default | Description | Recommended | |-----------|------|---------|-------------|-------------| | max_tokens | number | 10000 | Token threshold for compression | 5000-20000 | | preserve_recent | number | 4 | Number of recent messages to keep | 4-6 | | auto_compact | boolean | true | Enable automatic compression | true | | model | string | '' | Model for summary generation | Global default |

Configuration Examples

Conservative Mode (frequent compression, max token savings):

{
  "max_tokens": 5000,
  "preserve_recent": 6
}

Aggressive Mode (fewer compressions, more context retained):

{
  "max_tokens": 20000,
  "preserve_recent": 3
}

📊 How It Works

Compression Flow

1. Monitor token usage
   ↓
2. Exceeds threshold (90%)?
   ├─ No → Continue conversation
   └─ Yes → Trigger compression
        ↓
3. Keep last N messages (default: 4)
   ↓
4. Compress old messages into structured summary
   ├─ Scope: Statistics
   ├─ Recent requests: Last 3 user requests
   ├─ Pending work: To-dos
   ├─ Key files: Important files
   ├─ Tools used: Tools mentioned
   └─ Key timeline: Conversation timeline
   ↓
5. Replace old messages with System summary
   ↓
6. Seamlessly continue conversation

Fallback Mechanism

When LLM is unavailable, automatically falls back to code extraction mode:

🛠️ Troubleshooting

Common Issues

#### 1. Compression Not Triggered

Cause: Token count below threshold Solution:

# Check current token usage
openclaw compact-status
Lower threshold for testing
openclaw compact --force

#### 2. Poor Summary Quality

Cause: LLM misconfigured or unavailable Solution:

#### 3. Context Loss After Compression

Cause: preserve_recent set too low Solution:

{
  "preserve_recent": 6  // Increase to 6 or more
}

#### 4. Plugin Not Recognized

Cause: Missing plugin configuration Solution:

# Check plugin status
openclaw plugins list | grep compact
Ensure plugin is in plugins.allow in openclaw.json

📈 Performance Metrics

🧪 Testing

# Run tests
npm test
Check coverage (163 tests, 82.78%)
npm run test:coverage

📚 Technical Documentation

For detailed API documentation and examples, see README.md.

Core API

// Compress session
const result = await compactSession(messages, config);
// Check if compression is needed
const needsCompact = shouldCompact(messages, config);
// Estimate token count
const tokens = estimateTokenCount(messages);

🤝 Contributing

Contributions are welcome! Please submit Issues and Pull Requests.

1. Fork the project 2. Create a feature branch 3. Commit changes 4. Push to the branch 5. Open a Pull Request

📄 License

MIT License

Status: ✅ Stable Release Tests: ✅ 163/163 Passing Coverage: 📈 82.78% ClawHub (Code Plugin): ✅ Published (openclaw-session-compact@1.2.1) ClawHub (Skill): ✅ Published (session-compact-skill@1.2.1) Version: v1.2.1 Maintainer: SDC-creator

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "allow": ["openclaw-session-compact"],
    "entries": {
      "openclaw-session-compact": {
        "enabled": true,
        "config": {
          "max_tokens": 10000,
          "preserve_recent": 4,
          "auto_compact": true,
          "model": ""
        }
      }
    }
  }
}

重要：配置参数从 OpenClaw 配置系统读取。修改配置后需要重启 Gateway：

openclaw gateway restart