jasper-context-compactor 0.2.2 → 0.3.1

package/README.md

@@ -1,27 +1,65 @@
-# Context Compactor
+# Jasper Context Compactor
 
 > Token-based context compaction for OpenClaw with local models (MLX, llama.cpp, Ollama)
 
-## Why?
+## The Problem
 
-Local LLM servers don't report context overflow errors like cloud APIs do. OpenClaw's built-in compaction relies on these errors to trigger. This plugin estimates tokens client-side and proactively summarizes older messages before hitting the model's limit.
+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
-# One command setup (installs + configures)
 npx jasper-context-compactor setup
+```
 
-# Restart gateway
+**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 your model** — Suggests appropriate token limits based on your setup
+4. ✅ **Let you customize** — Enter your own values if auto-detection doesn't match
+5. ✅ **Update config safely** — Adds the plugin with your chosen settings
+
+Then restart OpenClaw:
+```bash
 openclaw gateway restart
 ```
 
-That's it! The setup command:
-- Copies plugin files to `~/.openclaw/extensions/context-compactor/`
-- Adds plugin config to `openclaw.json` with sensible defaults
+## 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 (chars ÷ 4)
+2. If over `maxTokens`, splits messages into "old" and "recent"  
+3. Summarizes old messages using your session model
+4. Injects summary as context — conversation continues seamlessly
+
+## Commands
+
+After setup, use these in chat:
+
+| Command | Description |
+|---------|-------------|
+| `/context-stats` | Show current token usage and limits |
+| `/compact-now` | Clear cache and force fresh compaction |
 
 ## Configuration
 
+The setup configures these values in `~/.openclaw/openclaw.json`:
+
 ```json
 {
   "plugins": {
@@ -40,17 +78,43 @@ That's it! The setup command:
 }
 ```
 
-## Commands
+| Option | Description |
+|--------|-------------|
+| `maxTokens` | Trigger compaction above this (set to ~80% of your model's context) |
+| `keepRecentTokens` | Recent context to preserve (default: 25% of max) |
+| `summaryMaxTokens` | Max tokens for the summary (default: 12.5% of max) |
+| `charsPerToken` | Token estimation ratio (4 works for English) |
 
-- `/context-stats` — Show current token usage
-- `/compact-now` — Force fresh compaction on next message
+## Restoring Your Config
 
-## How It Works
+Setup always backs up first. To restore:
+
+```bash
+# List backups
+ls ~/.openclaw/backups/
+
+# Restore (use the timestamp from your backup)
+cp ~/.openclaw/backups/openclaw-2026-02-11T08-00-00-000Z.json ~/.openclaw/openclaw.json
+
+# Restart
+openclaw gateway restart
+```
+
+## Uninstall
+
+```bash
+# Remove plugin files
+rm -rf ~/.openclaw/extensions/context-compactor
+
+# Remove from config (edit openclaw.json and delete the context-compactor entry)
+# Or restore from backup
+```
+
+## Links
 
-1. Before each agent turn, estimates total context tokens
-2. If over `maxTokens`, splits messages into "old" and "recent"
-3. Summarizes old messages using the session model
-4. Injects summary + recent messages as context
+- **npm:** https://www.npmjs.com/package/jasper-context-compactor
+- **GitHub:** https://github.com/E-x-O-Entertainment-Studios-Inc/openclaw-context-compactor
+- **ClawHub:** https://clawhub.ai/skills/context-compactor
 
 ## License
 

package/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Context Compactor CLI
+ * Jasper Context Compactor CLI
  * Setup script with interactive token limit configuration
  */
 
@@ -10,6 +10,7 @@ const os = require('os');
 const readline = require('readline');
 
 const OPENCLAW_CONFIG = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+const OPENCLAW_BACKUPS = path.join(os.homedir(), '.openclaw', 'backups');
 const OPENCLAW_EXTENSIONS = path.join(os.homedir(), '.openclaw', 'extensions', 'context-compactor');
 const OLD_EXTENSIONS = path.join(os.homedir(), '.openclaw', 'extensions', 'openclaw-context-compactor');
 
@@ -35,31 +36,35 @@ function prompt(question) {
   });
 }
 
+function backupConfig() {
+  if (!fs.existsSync(OPENCLAW_CONFIG)) return null;
+  
+  fs.mkdirSync(OPENCLAW_BACKUPS, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(OPENCLAW_BACKUPS, `openclaw-${timestamp}.json`);
+  
+  fs.copyFileSync(OPENCLAW_CONFIG, backupPath);
+  return backupPath;
+}
+
 async function detectModelContextWindow(config) {
-  // Try to detect from OpenClaw config
   const model = config?.agents?.defaults?.model?.primary;
-  
   if (!model) return null;
   
-  // Common context windows (conservative estimates)
   const knownContexts = {
-    // Anthropic
     'anthropic/claude-opus': 200000,
     'anthropic/claude-sonnet': 200000,
     'anthropic/claude-haiku': 200000,
-    // OpenAI
     'openai/gpt-4': 128000,
     'openai/gpt-4-turbo': 128000,
     'openai/gpt-3.5-turbo': 16000,
-    // Local models (common sizes)
-    'mlx': 8000,
-    'ollama': 8000,
-    'llama': 8000,
+    'mlx': 32000,        // Most MLX models support 32K+
+    'ollama': 32000,     // Most Ollama models support 32K+
+    'llama': 32000,
     'mistral': 32000,
     'qwen': 32000,
   };
   
-  // Check for exact match first
   for (const [pattern, tokens] of Object.entries(knownContexts)) {
     if (model.toLowerCase().includes(pattern.toLowerCase())) {
       return { model, tokens, source: 'detected' };
@@ -70,18 +75,49 @@ async function detectModelContextWindow(config) {
 }
 
 async function setup() {
-  log('Context Compactor — Setup');
-  console.log('='.repeat(50));
+  console.log('');
+  log('Jasper Context Compactor — Setup');
+  console.log('='.repeat(55));
+  
+  // Explain what we're going to do
+  console.log('');
+  console.log('  This setup will:');
+  console.log('');
+  console.log('  1. Copy plugin files to ~/.openclaw/extensions/');
+  console.log('  2. Add plugin config to your openclaw.json');
+  console.log('  3. Help you configure token limits for your model');
+  console.log('');
+  console.log('  🔒 Privacy: Everything runs locally. Nothing is sent externally.');
+  console.log('  📁 Your config will be backed up before any changes.');
+  console.log('');
+  
+  const proceed = await prompt('  Continue? (y/n): ');
+  if (proceed.toLowerCase() !== 'y' && proceed.toLowerCase() !== 'yes') {
+    console.log('\n  Setup cancelled.\n');
+    process.exit(0);
+  }
   
   // Check if OpenClaw is installed
   const openclawDir = path.join(os.homedir(), '.openclaw');
   if (!fs.existsSync(openclawDir)) {
+    console.log('');
     error('OpenClaw not detected (~/.openclaw not found)');
-    console.log('Install OpenClaw first: https://docs.openclaw.ai');
+    console.log('  Install OpenClaw first: https://docs.openclaw.ai');
     process.exit(1);
   }
   
-  // Copy plugin files to extensions directory
+  // Backup config FIRST
+  console.log('');
+  log('Backing up config...');
+  const backupPath = backupConfig();
+  if (backupPath) {
+    console.log(`  ✓ Backup saved: ${backupPath}`);
+    console.log('  → Restore with: cp "' + backupPath + '" ~/.openclaw/openclaw.json');
+  } else {
+    console.log('  ⚠ No existing config to backup');
+  }
+  
+  // Copy plugin files
   console.log('');
   log('Installing plugin files...');
   fs.mkdirSync(OPENCLAW_EXTENSIONS, { recursive: true });
@@ -98,7 +134,7 @@ async function setup() {
     }
   }
   
-  // Clean up old package name if it exists
+  // Clean up old package name
   if (fs.existsSync(OLD_EXTENSIONS)) {
     try {
       fs.rmSync(OLD_EXTENSIONS, { recursive: true });
@@ -126,12 +162,10 @@ async function setup() {
   console.log('  To set the right limit, I can check your OpenClaw config');
   console.log('  to see what model you\'re using.');
   console.log('');
-  console.log('  🔒 Privacy: This runs 100% locally. Nothing is sent externally.');
-  console.log('');
   
   const checkConfig = await prompt('  Check your config for model info? (y/n): ');
   
-  let maxTokens = 8000; // Default
+  let maxTokens = 16000;  // OpenClaw minimum
   let detectedInfo = null;
   
   if (checkConfig.toLowerCase() === 'y' || checkConfig.toLowerCase() === 'yes') {
@@ -142,7 +176,6 @@ async function setup() {
       console.log(`  ✓ Detected model: ${detectedInfo.model}`);
       console.log(`  ✓ Context window: ~${detectedInfo.tokens.toLocaleString()} tokens`);
       
-      // Suggest a safe limit (leave 20% headroom)
       const suggested = Math.floor(detectedInfo.tokens * 0.8);
       console.log(`  → Suggested maxTokens: ${suggested.toLocaleString()} (80% of context)`);
       console.log('');
@@ -161,30 +194,48 @@ async function setup() {
     }
   }
   
-  // If we still don't have a good value, ask manually
+  // Manual entry if needed
   if (maxTokens === 8000 && (!detectedInfo || !detectedInfo.tokens)) {
     console.log('');
     console.log('  Common context windows:');
-    console.log('    • MLX / llama.cpp (small): 4,000 - 8,000');
-    console.log('    • Mistral / Qwen (medium): 32,000');
-    console.log('    • Claude / GPT-4 (large):  128,000+');
+    console.log('    • MLX / llama.cpp (small):  4,000 - 8,000');
+    console.log('    • Mistral / Qwen (medium):  32,000');
+    console.log('    • Claude / GPT-4 (large):   128,000+');
+    console.log('');
+    console.log('  ⚠️  Minimum recommended: 16,000 tokens (OpenClaw requirement)');
     console.log('');
     console.log('  Check your model\'s docs or LM Studio/Ollama settings.');
     console.log('  Config location: ~/.openclaw/openclaw.json');
     console.log('');
     
-    const customTokens = await prompt('  Enter maxTokens (default 8000): ');
+    const customTokens = await prompt('  Enter maxTokens (default 16000, minimum 16000): ');
     if (/^\d+$/.test(customTokens)) {
       maxTokens = parseInt(customTokens, 10);
+    } else {
+      maxTokens = 16000;
     }
   }
   
-  // Calculate keepRecentTokens (25% of max)
+  // Enforce minimum
+  const MIN_TOKENS = 16000;
+  if (maxTokens < MIN_TOKENS) {
+    console.log('');
+    console.log(`  ⚠️  Warning: ${maxTokens} tokens is below OpenClaw's minimum of ${MIN_TOKENS}.`);
+    console.log(`     Increasing to ${MIN_TOKENS} to prevent agent failures.`);
+    console.log('');
+    console.log('  If your model truly has a smaller context window, consider:');
+    console.log('    • Using a larger model (Qwen 7B+ or Mistral 7B+)');
+    console.log('    • Using the cloud fallback for complex tasks');
+    console.log('');
+    maxTokens = MIN_TOKENS;
+  }
+  
+  // Calculate derived values
   const keepRecentTokens = Math.floor(maxTokens * 0.25);
   const summaryMaxTokens = Math.floor(maxTokens * 0.125);
   
   console.log('');
-  console.log(`  Configuration:`);
+  console.log('  Final configuration:');
   console.log(`    maxTokens:        ${maxTokens.toLocaleString()}`);
   console.log(`    keepRecentTokens: ${keepRecentTokens.toLocaleString()} (25%)`);
   console.log(`    summaryMaxTokens: ${summaryMaxTokens.toLocaleString()} (12.5%)`);
@@ -193,11 +244,9 @@ async function setup() {
   console.log('');
   log('Updating OpenClaw config...');
   
-  // Initialize plugins structure if needed
   if (!config.plugins) config.plugins = {};
   if (!config.plugins.entries) config.plugins.entries = {};
   
-  // Add/update plugin config
   config.plugins.entries['context-compactor'] = {
     enabled: true,
     config: {
@@ -208,49 +257,56 @@ async function setup() {
     }
   };
   
-  // Write back with nice formatting
   fs.writeFileSync(OPENCLAW_CONFIG, JSON.stringify(config, null, 2) + '\n');
   console.log('  ✓ Saved to openclaw.json');
   
+  // Done!
   console.log('');
-  console.log('='.repeat(50));
+  console.log('='.repeat(55));
   log('Setup complete!');
   console.log('');
-  console.log('Next steps:');
-  console.log('  1. Restart OpenClaw: openclaw gateway restart');
-  console.log('  2. Check status in chat: /context-stats');
+  console.log('  Next steps:');
+  console.log('    1. Restart OpenClaw: openclaw gateway restart');
+  console.log('    2. Check status in chat: /context-stats');
   console.log('');
-  console.log('To adjust later, edit ~/.openclaw/openclaw.json');
-  console.log('under plugins.entries["context-compactor"].config');
+  console.log('  To adjust later:');
+  console.log('    Edit ~/.openclaw/openclaw.json');
+  console.log('    Look for plugins.entries["context-compactor"].config');
+  console.log('');
+  if (backupPath) {
+    console.log('  To restore original config:');
+    console.log(`    cp "${backupPath}" ~/.openclaw/openclaw.json`);
+    console.log('');
+  }
 }
 
 function showHelp() {
   console.log(`
-Context Compactor
-Token-based context compaction for local models
+Jasper Context Compactor
+Token-based context compaction for local models (MLX, llama.cpp, Ollama)
 
 USAGE:
-  npx openclaw-context-compactor setup    Install and configure plugin
-  npx openclaw-context-compactor help     Show this help
+  npx jasper-context-compactor setup    Install and configure plugin
+  npx jasper-context-compactor help     Show this help
 
 WHAT IT DOES:
-  - Copies plugin files to ~/.openclaw/extensions/context-compactor/
-  - Detects your model's context window (with permission)
-  - Configures appropriate token limits
-  - Enables automatic context compaction for local models
+  Local LLMs don't report context overflow errors like cloud APIs.
+  This plugin estimates tokens client-side and proactively summarizes
+  older messages before hitting your model's context limit.
 
-CONFIGURATION:
-  After setup, adjust in openclaw.json:
-  
-  "context-compactor": {
-    "enabled": true,
-    "config": {
-      "maxTokens": 8000,       // Your model's context limit minus buffer
-      "keepRecentTokens": 2000 // Recent context to preserve
-    }
-  }
+SETUP PROCESS:
+  1. Backs up your openclaw.json (with restore instructions)
+  2. Copies plugin files to ~/.openclaw/extensions/
+  3. Asks permission before reading your config
+  4. Detects your model and suggests appropriate token limits
+  5. Lets you customize or enter values manually
+  6. Updates openclaw.json with the plugin config
+
+PRIVACY:
+  Everything runs 100% locally. Nothing is sent to external servers.
+  We only read your local config file (with your permission).
 
-COMMANDS (in chat):
+COMMANDS (in chat after setup):
   /context-stats    Show current token usage
   /compact-now      Force fresh compaction
 `);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "jasper-context-compactor",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Context compaction plugin for OpenClaw - works with local models (MLX, llama.cpp) that don't report token limits",
   "main": "index.ts",
   "bin": {
     "context-compactor": "./cli.js"
   },
   "openclaw": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "keywords": [
     "openclaw",