context-capsule

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.