# Context Capsule

> Compresses older OpenClaw agent session history into a bounded, lane-change-aware context capsule — keeps recent messages verbatim, flags abandoned directions, quarantines injected instructions, and redacts secrets. Local, deterministic, any model.

- **Type:** Skill
- **Install:** `agentstack add skill-parad0x-labs-openclaw-skills-context-capsule`
- **Verified:** Pending review
- **Seller:** [Parad0x-Labs](https://agentstack.voostack.com/s/parad0x-labs)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Parad0x-Labs](https://github.com/Parad0x-Labs)
- **Source:** https://github.com/Parad0x-Labs/openclaw-skills/tree/main/skills/context-capsule

## Install

```sh
agentstack add skill-parad0x-labs-openclaw-skills-context-capsule
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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, so the capsule
  keeps **79% of key signals at ~5× reduction and 93% at ~3.4×** on real
  sessions (measured, see `test/fidelity-bench.mjs`).

> **Self-contained (v1.6.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

|                       | Without | With     |
| --------------------- | ------- | -------- |
| Prompt history sent   | Full transcript | Capsule + recent tail |
| Compression trigger   | N/A     | Message + token threshold |
| Runtime dependencies  | N/A     | Node 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Parad0x-Labs](https://github.com/Parad0x-Labs)
- **Source:** [Parad0x-Labs/openclaw-skills](https://github.com/Parad0x-Labs/openclaw-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-parad0x-labs-openclaw-skills-context-capsule
- Seller: https://agentstack.voostack.com/s/parad0x-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.