context-compactor

# Context Compactor

Automatic context compaction for OpenClaw when using local models that don't properly report token limits or context overflow errors.

## The Problem

Cloud APIs (Anthropic, OpenAI) report context overflow errors, allowing OpenClaw's built-in compaction to trigger. Local models (MLX, llama.cpp, Ollama) often:

- Silently truncate context
- Return garbage when context is exceeded
- Don't report accurate token counts

This leaves you with broken conversations when context gets too long.

## The Solution

Context Compactor estimates tokens client-side and proactively summarizes older messages before hitting the model's limit.

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│  1. Message arrives                                         │
│  2. before_agent_start hook fires                           │
│  3. Plugin estimates total context tokens                   │
│  4. If over maxTokens:                                      │
│     a. Split into "old" and "recent" messages              │
│     b. Summarize old messages (LLM or fallback)            │
│     c. Inject summary as compacted context                 │
│  5. Agent sees: summary + recent + new message             │
└─────────────────────────────────────────────────────────────┘
```

## Installation

```bash
# One command setup (recommended)
npx jasper-context-compactor setup

# Restart gateway
openclaw gateway restart
```

The setup command automatically:
- Copies plugin files to `~/.openclaw/extensions/context-compactor/`
- Adds plugin config to `openclaw.json` with sensible defaults

## Configuration

Add to `openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "context-compactor": {
        "enabled": true,
        "config": {
          "maxTokens": 8000,
          "keepRecentTokens": 2000,
          "summaryMaxTokens": 1000,
          "charsPerToken": 4
        }
      }
    }
  }
}
```

### Options

| Option | Default | Description |
|---...

# Jasper Context Compactor

> Token-based context compaction for OpenClaw with local models (MLX, llama.cpp, Ollama)

## The Problem

Local LLMs don't report context overflow errors like cloud APIs do. When context gets too long, they either:
- Silently truncate your conversation
- Return garbage output
- Crash without explanation

OpenClaw's built-in compaction relies on error signals that local models don't provide.

## The Solution

Jasper Context Compactor estimates tokens client-side and proactively summarizes older messages before hitting your model's limit. No more broken conversations.

## Quick Start

```bash
npx jasper-context-compactor setup
```

**The setup will:**

1. ✅ **Back up your config** — Saves `openclaw.json` to `~/.openclaw/backups/` with restore instructions
2. ✅ **Ask permission** — Won't read your config without consent
3. ✅ **Detect local models** — Automatically identifies Ollama, llama.cpp, MLX, LM Studio providers
4. ✅ **Suggest token limits** — Based on your model's contextWindow from config
5. ✅ **Let you customize** — Enter your own values if auto-detection doesn't match
6. ✅ **Update config safely** — Adds the plugin with your chosen settings

### Supported Local Providers

The setup automatically detects these providers (primary or fallback):
- **Ollama** — Any provider with `ollama` in name or `:11434` in baseUrl
- **llama.cpp** — llamacpp provider
- **MLX** — mlx provider  
- **LM Studio** — lmstudio provider
- **friend-gpu** — Custom GPU servers
- **OpenRouter** — When routing to local models
- **Local network** — Any provider with localhost, 127.0.0.1, or Tailscale IP in baseUrl

Then restart OpenClaw:
```bash
openclaw gateway restart
```

## Privacy

🔒 **Everything runs 100% locally.** Nothing is sent to external servers.

The setup only reads your local `openclaw.json` file (with your permission) to detect your model and suggest appropriate limits.

## How It Works

1. Before each message, estimates total context tokens...