Context Capsule

Compress older agent session history before it hits the LLM, so long chats stop re-sending the full transcript every turn. It keeps the recent tail verbatim and turns older history into a bounded extractive capsule with decisions, tasks, errors, paths, links, questions, and durable facts. Works with any model — Claude, GPT, Ollama, Mistral, LM Studio.

What sets it apart:

• Lane-change aware. When the session pivots ("replace X with Y", "forget X, use Y instead"), the capsule marks the abandoned direction as superseded and keeps the live one, so the model is steered away from a dropped plan. On the 6-case pivot set in test/supersession-bench.mjs (5 pivots, 1 no-pivot control, 6 abandoned subjects) v1.7.0 strikes or omits 6 of 6 abandoned subjects and flags 0 live choices at budgets 700 and 1,400; npm test fails below 83% or on any wrongly flagged live choice. Pivots stated without an explicit cue are not detected.
• High fidelity per token. Distinctive signals — file paths, IDs, ports, URLs, commands, errors, decisions — are emitted as dense atoms. As of v1.7.0, a lone value (a bare port 5433, an issue ref #4821, a version v2.13.0, an ISO date, a hyphenated code like NEEDLE-ZX-7742) is emitted as its own atom, so it survives compression even when its surrounding sentence loses the budget race (test/value-survival.test.mjs). On the public 109-message fixture in bench/fixtures, with default settings the model receives 2,061 estimated tokens per call instead of 7,281, and 21 of 40 fixture questions still have their answer keywords in that text (35 with full history). Key-signal recall of the capsule alone is 65% at a 1,200-token budget and 86% at 2,000 (test/fidelity-bench.mjs, which also runs on your own ~/.openclaw sessions). These are availability checks, not model-answer accuracy, which has not been measured. Details: docs/CONTEXT_CAPSULE_BENCHMARK.md in the repository.

Self-contained (v1.7.0): The compression core is bundled directly in this skill (src/compression.ts). There is no external runtime dependency, and the plugin makes no network, file-system, or on-chain calls. Everything runs locally using only Node's built-in zlib and crypto, and is fully deterministic. Capsules carry a schema tag (context-capsule.v2).

Protections (defense-in-depth, all checked by npm test, which runs in the repository's skills CI lane and before every publish):

• Secret redaction (every surface). API keys (OpenAI, Anthropic, AWS, Google, GitHub classic + fine-grained, GitLab, npm, Slack, Stripe, SendGrid, Twilio), JWTs, PEM blocks, URL basic-auth, DATABASE_URL= DSNs, and key=value credentials are detected by prefix/shape/context — never by raw entropy, so public IDs (git SHAs, UUIDs, chain addresses) are untouched. Redaction runs before compression, so no secret survives even in the zlib audit blob, and again on output — the core never emits a secret even if called directly. Each redaction carries a one-way SHA-256 fingerprint ([REDACTED_AWS_KEY#a1b2c3d4]) so the same key is correlatable across turns without ever exposing its value. Best-effort pattern matching — strong, not a guarantee for the most sensitive chats.
• Injection quarantine — instruction-injection patterns in older history ("ignore previous instructions", "you are now…", "reveal your prompt") are wrapped as inert untrusted text, never surfaced as a live instruction.
• Bounded work — every extraction pass runs on size-capped input, so a megabyte message or an adversarial string finishes in milliseconds instead of hanging the turn.

When to use

• Long-running agent sessions (default: more than 20 messages) where the transcript is large and you want to cut per-call token cost.
• Any model/provider — local or hosted.

When NOT to use

• Sessions that require exact, verbatim transcript fidelity. Older history is summarized into a compact capsule; detail and nuance can be lost. Only the most recent 10 messages are kept verbatim.
• As your only safeguard for secrets/PII. The vault scan is best-effort, and the compressed history is injected into the system context position.

How it works

Keeps the last 10 messages verbatim by default. Older history is zlib-compressed for auditability, then converted into a model-readable extractive capsule. The model sees compact sections for decisions/constraints, tasks, errors, files, commands, links, questions, and durable facts. The capsule is capped by maxCapsuleTokens and adapts to the host token budget with capsuleTokenRatio.

Savings

Install

This skill is self-contained — no extra packages to install. Register it as your context engine in openclaw.json:

{
  "plugins": {
    "slots": { "contextEngine": "context-capsule" }
  }
}

Optional config (defaults shown):

{
  "plugins": {
    "entries": {
      "context-capsule": {
        "enabled": true,
        "config": {
          "minMessages": 20,
          "keepRecentMessages": 10,
          "maxCapsuleTokens": 1400,
          "capsuleTokenRatio": 0.14,
          "minCompressTokens": 900
        }
      }
    }
  }
}

Source

github.com/Parad0x-Labs/openclaw-skills/tree/main/skills/context-capsule

The standalone library (@parad0x_labs/context-capsule) is published separately on npm for non-OpenClaw use; this skill vendors only the two pure functions it needs and does not depend on it at runtime.

If Context Capsule is useful to you, a star on ClawHub helps other agent builders find it.