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 never wanders back into a dropped plan. On a held-out pivot set it cleans 83% of abandoned subjects with zero wrongly flagged live choices.
• 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 — CI-tested in test/value-survival.test.mjs. On the maintainer's own real sessions the capsule kept ~79% of key signals at ~5× reduction and ~93% at ~3.4×; test/fidelity-bench.mjs measures this against your own ~/.openclaw sessions (run it on your data to reproduce — the figures are from private sessions, not a repo fixture).

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 CI-gated by npm test):

• 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#

WithoutWithPrompt history sentFull transcriptCapsule + recent tailCompression triggerN/AMessage + token thresholdRuntime dependenciesN/ANode built-ins only

Install#

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

jsonc

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

Optional config (defaults shown):

jsonc

{
  "plugins": {
    "entries": {
      "context-capsule": {
        "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 quietly shrinking your token bill, a ⭐ on ClawHub helps other agent builders find it.