home / skills / openclaw / skills / context-budgeting-v2

context-budgeting-v2 skill

safe

This skill helps manage and optimize the OpenClaw context window by partitioning, checkpointing, and lifecycle rules to reduce costs and latency.

npx playbooks add skill openclaw/skills --skill context-budgeting-v2

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: context-budgeting
description: Manage and optimize OpenClaw context window usage via partitioning, pre-compression checkpointing, and information lifecycle management. Use when the session context is near its limit (>80%), when the agent experiences "memory loss" after compaction, or when aiming to reduce token costs and latency for long-running tasks.
---

# Context Budgeting Skill

This skill provides a systematic framework for managing the finite context window (RAM) of an OpenClaw agent.

## Core Concepts

### 1. Information Partitioning
- **Objective/Goal (10%)**: Core task instructions and active constraints.
- **Short-term History (40%)**: Recent 5-10 turns of raw dialogue.
- **Decision Logs (20%)**: Summarized outcomes of past steps ("Tried X, failed because Y").
- **Background/Knowledge (20%)**: High-relevance snippets from MEMORY.md.

### 2. Pre-compression Checkpointing (Mandatory)
Before any compaction (manual or automatic), the agent MUST:
1.  **Generate Checkpoint**: Update `memory/hot/HOT_MEMORY.md` with:
    - **Status**: Current task progress.
    - **Key Decision**: Significant choices made.
    - **Next Step**: Immediate action required.
2.  **Run Automation**: Execute `scripts/gc_and_checkpoint.sh` to trigger the physical cleanup.

## Automation Tool: `gc_and_checkpoint.sh`
Located at: `skills/context-budgeting/scripts/gc_and_checkpoint.sh`

**Usage**: 
- Run this script after updating `HOT_MEMORY.md` to finalize the compaction process without restarting the session.

## Integration with Heartbeat
Heartbeat (every 30m) acts as the Garbage Collector (GC):
1.  Check `/status`. If Context > 80%, trigger the **Checkpointing** procedure.
2.  Clear raw data (e.g., multi-megabyte JSON outputs) once the summary is extracted.

Overview

This skill manages and optimizes an OpenClaw agent's finite context window through partitioning, checkpointing, and lifecycle rules. It reduces token cost and latency for long-running sessions while preventing memory loss after compaction. Use it to keep critical instructions hot and archive less-relevant data safely.

How this skill works

The skill divides session content into prioritized partitions (objective, short-term history, decision logs, background knowledge) and enforces size targets for each. Before any compaction it requires a mandatory pre-compression checkpoint that records status, key decisions, and next steps to a hot-memory file. An automation script finalizes the cleanup, and a heartbeat process monitors context usage to trigger checkpointing when thresholds are exceeded.

When to use it

Session context usage exceeds ~80% of the window.
Agent experiences loss of recent decisions or degraded planning after compaction.
Running long-lived tasks where token cost or latency grows with context size.
You need deterministic checkpoints before automated garbage collection.
When you must retain high-value instructions while pruning verbose outputs.

Best practices

Keep the Objective/Goal partition small and explicit (≈10% of budget).
Store only the last 5–10 turns in raw short-term history; summarize older turns.
Write concise decision logs capturing action, outcome, and reason for future recall.
Always run the gc_and_checkpoint.sh script after updating the hot-memory checkpoint.
Let the heartbeat process act as the GC trigger but validate checkpoints manually for critical flows.

Example use cases

A research agent running multi-hour experiments that must preserve core hypotheses but drop verbose outputs.
A customer-support bot that must retain recent dialogue turns while archiving older conversation summaries.
An orchestration agent coordinating subtasks that needs reliable checkpoints before aggressive compaction.
Agents producing large JSON or binary outputs that should be removed from raw context after summarization.
Automated pipelines where periodic heartbeat-driven cleanup prevents unexpected token overrun.

FAQ

What must a checkpoint include?

A checkpoint must record current status, the key decision(s) made, and the immediate next step in the hot-memory file.

When does the heartbeat trigger checkpointing?

Heartbeat checks context usage every 30 minutes and triggers checkpointing when context exceeds about 80%.