Skill: klautimus/openclaw-token-memory-optimizer (version 1.0.0)

--- name: token-optimizer description: Optimization suite for OpenClaw agents to prevent token leaks and context bloat. Use when an agent needs to implement background task isolation (Cron) or a Reset & Summarize workflow (RAG). version: 1.1.0 authors: - Pépère (shAde) - Zayan (Clément) --- # Token Optimizer Skill This skill provides the procedural knowledge to keep your OpenClaw instance lean and efficient. ## Quick Reference | Problem | Solution | |---------|----------| | Background tasks bloating context | Cron isolation (`sessionTarget: "isolated"`) | | Reading entire history every turn | Local RAG with `memory_search` | | Context exceeds 100k tokens | Reset & Summarize protocol | | Finding old conversations | Session transcript indexing | --- ## Workflow 1: Periodic Task Isolation To prevent background tasks from bloating your main conversation context, always isolate them. ### Steps 1. Locate your `openclaw.json` config. 2. In the `cron.jobs` array, set `sessionTarget: "isolated"` for any task that doesn't need to be part of the main chat history. 3. Use the `message` tool within the task's payload if human intervention is required. ### Example Config ```json { "cron": { "jobs": [ { "name": "Background Check", "schedule": { "kind": "every", "everyMs": 1800000 }, "sessionTarget": "isolated", "payload": { "kind": "agentTurn", "message": "Check for updates. If found, use message tool to notify user.", "deliver": true } } ] } } ``` ### Key Points - `sessionTarget: "isolated"` runs the task in a separate, transient session - Use `deliver: true` to send results back to the main channel - Isolated sessions don't pollute your main context with heartbeat/check history --- ## Workflow 2: Reset & Summarize (The "Digital Soul" Protocol) When your context usage (visible via `📊 session_status`) exceeds 100k tokens, perform a manual consolidation. ### Steps 1. **Check Context**: Run `📊 session_status` to see current token usage 2. **Scan History**: Review the current session for new facts, preferences, or project updates 3. **Update MEMORY.md**: Append these new facts to your long-term memory file 4. **Daily Log**: Ensure `memory/YYYY-MM-DD.md` is up to date with today's events 5. **Restart**: Run `openclaw gateway restart` to clear the active history ### When to Trigger - Context > 100k tokens - Session running for several days - Noticeably slower responses - User explicitly requests a "fresh start" --- ## Workflow 3: Local RAG Configuration For efficient recall without token burn, configure local embeddings. ### Configuration (`openclaw.json`) ```json { "memorySearch": { "embedding": { "provider": "local", "model": "hf:second-state/All-MiniLM-L6-v2-Embedding-GGUF" }, "store": "sqlite", "paths": ["memory/", "MEMORY.md"], "extraPaths": [] } } ``` ### Usage Use `memory_search` to retrieve context from your logs instead of loading everything: ``` memory_search(query="what did we decide about the API design") ``` The tool returns relevant snippets with file paths and line numbers. Use `memory_get` to pull specific sections. --- ## Workflow 4: Session Transcript Indexing (Advanced) Index your session transcripts (`.jsonl` files) for searchable conversation history. ### How It Works OpenClaw stores session transcripts in `~/.openclaw/sessions/`. These can be indexed for semantic search, allowing you to find old conversations without loading them into context. ### Configuration Add transcript paths to `memorySearch.extraPaths`: ```json { "memorySearch": { "extraPaths": [ "~/.openclaw/sessions/*.jsonl" ] } } ``` ### Best Practices - Index selectively (recent sessions, important conversations) - Use date-based filtering to limit search scope - Archive old transcripts to cold storage after indexing --- ## Workflow 5: Hybrid Search (Vector + BM25) Combine semantic search with keyword matching for more accurate retrieval. ### Why Hybrid? | Search Type | Strengths | Weaknesses | |-------------|-----------|------------| | Vector (semantic) | Finds conceptually similar content | May miss exact terms | | BM25 (keyword) | Finds exact matches | Misses synonyms/paraphrases | | **Hybrid** | Best of both worlds | Slightly more compute | ### How to Use When `memory_search` returns low-confidence results: 1. Try the search with different phrasing (semantic variation) 2. Search for exact keywords you remember (BM25 behavior) 3. Combine results manually if needed ### Future Enhancement OpenClaw's RAG system may support native hybrid search in future versions. For now, run multiple queries when precision matters. --- ## Troubleshooting ### "My context is growing too fast" 1. Check cron jobs: Are they isolated? 2. Check heartbeat frequency: Too frequent = more tokens 3. Are you loading large files unnecessarily? ### "memory_search returns nothing" 1. Verify `memorySearch` is configured in `openclaw.json` 2. Check that the embedding model is downloaded 3. Ensure memory files exist and have content ### "Restart didn't clear context" The restart clears the session history, but: - System prompt is always loaded - Workspace files (MEMORY.md, etc.) are injected fresh - This is by design for continuity --- ## Credits - **Pépère** (shAde) — Original concept and documentation - **Zayan** (Clément) — Implementation and testing *Built for the OpenClaw community.* 🦦😸


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)