dogtorjonah/context-warp-drive

Contribute to dogtorjonah/context-warp-drive development by creating an account on GitHub.

63 stars · 8 forks · TypeScript

README

Context Warp Drive Stop summarizing your agent's memory. LLM-written compaction burns a model round-trip, rewrites the conversation prefix, and can quietly drop the exact identifiers your agent needs. Fold it deterministically instead.

92.6% cache-read hit rate across 954 tool calls in a 1h49m agent marathon, measured from the provider usage ledger. In the included offline benchmark: −63% cost vs truncation, −72% vs summarization, with zero extra LLM calls and exact local BPE counts.

The Infinite Context Warp Engine. Keep long function-calling agent sessions under the context window without LLM summarization calls and without ending the session — preserve reusable prompt prefixes across ordinary turns and hard Rebirth boundaries, then page folded content back in when the recall layer sees it become relevant again. The core fold path is deterministic, zero-LLM, pure CPU, and zero I/O: identical inputs produce byte-identical output. Provider-agnostic message support includes Anthropic content blocks, OpenAI tool_calls, and Gemini parts. Optional host loops and the SQLite episode adapter perform I/O outside that core. Extracted from a production multi-agent system, where it folds context continuously across heterogeneous models and long-running agent workloads.

The repository contains 900+ deterministic test cases across rolling fold, recall, freeze, providers, task rail, and integration. Production cache rates come from the Claude provider usage ledger. The live benchmark uses provider-reported usage (ANTHROPIC_API_KEY=… npx tsx examples/benchmark-live.ts); the offline benchmark uses exact o200k_base BPE counts plus published pricing (npx tsx examples/benchmark.ts, deterministic, no key). Those are different evidence sources and are labeled separately below.

Provenance note (click to expand) This public package is production-derived. It is the portable distribution of an engine that runs live inside a private multi-agent system, so it deliberately uses generic WARP_* environment names, package-neutral examples, raw-history recovery wording, and tool-agnostic voice mining. The byte-identical invariant is local to this package — identical inputs produce identical folded views — and is not a claim of bit-for-bit parity with any private integration layer.

Performance & Economics Measured in production — real Claude workloads, provider cache telemetry The numbers that matter are from the production multi-agent system this engine powers — real Claude workloads running the fold/freeze engine continuously across hundreds of turns, measured from the provider's own usage ledger (cache-read tokens ÷ total input tokens):

Production Claude workload Measured turns Cache-read hit Fresh input Cache-read input

Opus 4.8 agent 691 89.6% 32.9M tok 292.6M tok

Opus agent 510 93.2% 32.6M tok 602.5M tok

~90% of all input tokens are served from cache across these high-turn Claude workloads — that is the byte-identical frozen-fold prefix doing its job, turn after turn, at $0.30/MTok cache reads instead of $3.00/MTok fresh input (Sonnet rates). Re-summarization rewrites the conversation segment when it compacts, while a sliding truncation window changes its earliest retained message; either can reduce reuse beyond any static system/tools prefix. The production rates above measure the behavior of this deployment, not a universal rate for every integration. Note on scope: the table above is live single-deployment production telemetry, not a controlled A/B study — there is no held-out arm running truncation or summarization against the same real workload for a head-to-head comparison. The offline/live benchmarks below fill that gap deterministically on a small session; a larger-scale controlled long-horizon comparison across strategies is future work, gated on compute budget, not on the mechanism being unproven. Reproduce it yourself — live, against Claude ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/benchmark-live.ts # default claude-sonnet-4-6 Real Claude calls every turn with Anthropic cache_control breakpoints, a real Claude summarizer (told to preserve every identifier — a fair fight), and the provider's own cache_read_input_tokens / cache_creation_input_tokens. A short 16-turn demo understates the production cache rate (caching needs a ≥1024-token prefix and CWD's advantage compounds over long sessions) — but it shows the mechanism on real telemetry, with CWD reading from cache while truncation and summarization rebuild their prefix. Offline deterministic demo (no API key, byte-identical every run) npx tsx examples/benchmark.ts — a 16-turn outage-debugging session, exact o200k_base BPE token counts (a portable proxy; Claude's tokenizer isn't public), claude-sonnet-4-6 list pricing — the same workhorse tier as the production table above, not a cheap demo tier. This is the CI smoke test; the summarizer is a transparent deterministic stand-in (it drops ids buried past its head cutoff — the failure mode the Coordinate Closet exists to avoid).

Strategy Input Cost Extra LLM Calls Fact Retention

Truncation (rolling window) $0.0516 0 44% (7/16)

LLM Summarization (stand-in) $0.0685 6 44% (7/16)

Context Warp Drive $0.0190 0 94% (15/16)

CWD is cheapest (−72% vs summarization, −63% vs truncation at the default Claude Sonnet rates), makes zero extra model calls, and beats truncation decisively on retention in this scenario. (A well-prompted real summarizer can match retention at higher cost — CWD's durable edge is cost + zero calls + determinism + byte-stable cache segments.) The engine is provider-agnostic: set WARP_BENCH_MODEL (and WARP_BENCH_PRICE_* for an unlisted model) to benchmark against any model, including OpenAI or a cheaper Claude tier. How it compares to LLM-based memory tools

Context Warp Drive Mem0 Letta Zep / Graphiti

Primary job Deterministic in-session compaction + recall Extracted long-term memory Persistent agent memory + context management Temporal knowledge-graph memory

Typical memory path Pure CPU fold/recall core Extraction model + configured stores Agent/model-managed blocks and retrieval Entity/edge extraction + graph retrieval

Prompt-cache effect Byte-stable sealed prefix between epochs; hard Rebirth preserves the static prefix and seals a new conversation baseline Integration-dependent Integration-dependent Integration-dependent

Runtime footprint Zero dependencies for the fold core SDK plus configured model/store backends Agent runtime/service plus memory backends Graph/storage plus model and embedding providers

License MIT Apache 2.0 Apache 2.0 Apache 2.0

These systems solve broader long-term-memory problems and can be complementary. Context Warp Drive's narrower design point is deterministic in-session compaction: zero model calls in the fold/recall core, no model-call latency, and explicit byte-stable cache segments rather than an opaque rewritten summary.

Try it in 5 minutes git clone https://github.com/dogtorjonah/context-warp-drive.git cd context-warp-drive && npm install npx tsx examples/benchmark.ts # no API key needed — deterministic, byte-identical every run For the live benchmark with real Claude calls and provider cache telemetry: ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/benchmark-live.ts

Why Every long agent session hits the same wall: the context window fills up. The usual answers are bad:

Truncation drops older history — the agent can lose what it was doing and the exact evidence behind it. LLM summarization ("compaction") costs a model call, adds latency, is non-deterministic, and rewrites the summarized conversation segment, reducing cache reuse beyond any unchanged static prefix.

Context Warp Drive instead deterministically folds old turns into compact structural skeletons (one line per tool call + retained reasoning), conserves salient exact identifiers (UUIDs, SHAs, paths, ports) in a budget-scored Coordinate Closet, and freezes sealed prefix segments for byte-identical reuse. With the recall layer wired in, touching a path can page its folded evidence back into the prepared view. No model calls in the fold/recall core; raw history stays intact.

Install Not published on npm yet. Install from source today: git clone https://github.com/dogtorjonah/context-warp-drive.git cd context-warp-drive npm install # runs `prepare` -> builds dist/ automatically

optional — only for the reference SQLite episode store:

Local tarball / future npm install dist/ is gitignored, so build before consuming the package from another project. For a local package install: npm run build # explicit fallback npm pack

from your consuming project:

If you ask an AI to wire it in Paste this:

Add context-warp-drive from the source checkout or local tarball, then wrap our function-calling message history with FoldSession.prepare() before each model call. Preserve raw history separately; send only the prepared messages view to the provider. Use cacheHot and stats for logging.

Then add the provider cache knob:

Provider What to do

Claude / Anthropic Use prepareAnthropicCachedRequest() from context-warp-drive/providers/anthropic with messages, sealedBoundary, system, and tools. It marks the relay-style breakpoints: tools, stable system head, sealed fold/rebirth boundary, and rolling tail. Default TTL is Anthropic's 5-minute cache shape; pass ttl: '1h' only when you want the paid 1-hour cache and merge the returned requestOptions/anthropicBeta into your SDK or fetch call. Log usage.cache_read_input_tokens and usage.cache_creation_input_tokens.

OpenAI Eligible exact prefixes cache automatically. Keep static tools/system/context first and pass the prepared messages. For GPT-5.6+ use a stable prompt_cache_key for the more reliable matching path and optionally place explicit breakpoints; log cache reads/writes from the response usage fields (cached_tokens, and cache_write_tokens where supported).

Gemini Implicit caching is automatic on Gemini 2.5+ when prefixes match. For a large static document/corpus, create an explicit Gemini cache separately and pass it as cachedContent; keep the folded conversation after that stable prefix. Log usage_metadata.

Gemini CLI Use context-warp-drive/providers/gemini-cli to fold the CLI-owned JSONL view, preserving the metadata header and rewriting with $set.messages + $set.lastUpdated.

Codex CLI Use context-warp-drive/providers/codex-cli to rebuild a folded Responses item seed for thread/inject_items from canonical transcript rows.

Claude Code CLI Use context-warp-drive/providers/claude-cli to build a folded Claude Code JSONL chain and atomically rewrite ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl before claude --resume.

Context Warp Drive keeps each sealed prefix byte-identical between epochs and preserves the static prefix across hard Rebirth boundaries. The provider SDK call still owns provider-specific cache settings.

Quickstart import { FoldSession } from 'context-warp-drive';

// One per conversation. Folds past the active window + preserves cacheable prefixes between epochs. const session = new FoldSession();

// Your full provider-shaped history (Anthropic / OpenAI / Gemini message objects). const history = [ { role: 'user', content: 'Investigate the failing test in src/parser.ts' }, // ... grows every turn ... ];

// Every turn, before you call the model: const { messages, cacheHot, stats } = session.prepare(history, { // Optional but recommended: pass real provider/relay input-token telemetry // from the previous turn. At 180k by default, FoldSession forces a fresh // fold epoch instead of hot-reusing into an oversized prompt. measuredInputTokens: previousUsage?.input_tokens, });

// `messages` is the compacted view to send. When `cacheHot` is true the prefix is // byte-identical to last turn, so the provider prompt cache is reused. await callYourModel(messages); // Anthropic / OpenAI / Gemini — the message shapes pass through unchanged console.log(`sent ${messages.length} msgs · cacheHot=${cacheHot} · savings=${stats.savingsPercent ?? 0}%`); That's the whole headline. For continuous always-lean folding, pass ALWAYS_ON_FOLD_CONFIG; to match your provider's real cache TTL, set freeze: { enabled: true, ttlMs: 3_600_000, maxTailChars: 150_000 }. The measured-token pressure guard defaults to DEFAULT_FOLD_PRESSURE_CEILING_TOKENS (180,000); pass pressureCeiling: false to disable it or pressureCeiling: 120_000 to tune it. See examples/anthropic-loop.ts and examples/openai-loop.ts for full tool loops.

Hard-epoch rebirth seed parity FoldSession.prepare() includes the portable hard-epoch path used by the Voxxo relay: it replaces the provider-visible view with one deterministic rebirth seed message, merges the triggering live user turn exactly once, and reseals that compact seed as the next frozen prefix. It fires automatically when real measured input tokens reach pressureCeiling; a harness can also force the same path directly: const outcome = session.prepare(history, { hardEpoch: true, hardEpochSeed: renderMyHostRebirthPackage(), // optional; omitted = raw trace seed measuredInputTokens: previousUsage?.input_tokens, }); For Anthropic, feed outcome.sealedBoundary to the provider helper every turn: import { prepareAnthropicCachedRequest } from 'context-warp-drive/providers/anthropic';

const cached = prepareAnthropicCachedRequest({ messages: outcome.messages as AnthropicMessage[], sealedBoundary: outcome.sealedBoundary, system: SYSTEM_PROMPT, tools: TOOLS, });

await client.messages.create( { model, max_tokens: 8192, ...cached.request }, cached.requestOptions, ); Choose an epoch policy There are two fully supported ways to run epoch transitions:

Policy What happens Best fit Cache behavior

Hard Rebirth epochs Replace the provider-visible conversation with one deterministic continuity seed, then seal that seed as the new baseline. Any long-running session; especially hosts that want the cleanest bounded reset policy, explicit same-instance resets, or process/model handoffs. The large static system/tools prefix remains reusable across the boundary. The regenerated continuity package is created once, then its sealed seed becomes the byte-stable baseline for following turns.

Tail epochs plus hard Rebirth epochs During a hot streak, fold only the new tail and append that band behind the frozen prefix. Escalate to a hard Rebirth at the measured ceiling, when runway or fold yield is exhausted, or when the host explicitly requests it. Hosts that want to minimize conversation-baseline rewrites between hard resets while an active streak remains healthy. Tail bands extend the existing frozen conversation baseline; the eventual hard Rebirth retains the static cacheable prefix and immediately establishes the next sealed baseline.

Hard Rebirth is not a degraded mode or a continuity compromise. The bundled rebirth-continuity paper reports first-action non-inferiority against a fair full-context compaction summary, depth-stable behavior through a 684th consecutive rebirth, and 92.8% cache-read on first boundary rows versus 94.5% on ordinary warm rows. The honest mechanism is a dominant static prefix plus a bounded, partly recreated continuity package—not reuse of the old conversation package. Those results come from one deployed system, and the controlled comparison covers first actions rather than full task outcomes. Tail epochs are therefore a cache-efficiency optimization between hard Rebirths, not a remedy for a weakness in Rebirth. With measured token telemetry, FoldSession uses the combined policy automatically: it appends productive tail bands while runway remains, then performs a hard Rebirth at the safety boundary. A host that prefers hard-only behavior can call prepare(..., { hardEpoch: true }) at each chosen boundary. Bounded is what makes it boundless. A hard epoch collapses the provider-visible view to one compact seed message — it does not discard anything from the host-owned raw trace. With recall wired in, the raw transcript remains backing for paging folded/pre-epoch content in when the agent re-touches a path, a claim, or a prior identifier, exactly as after an ordinary rolling fold. With measured pressure telemetry supplied before provider calls, the visible view stays below its safety ceiling while forward momentum — what the agent was doing, what it touched, what it decided — survives because recall and episodic memory read from the untouched raw trace, not from the collapsed view. The engine is deliberately bounded; that boundedness is what lets a session run indefinitely instead of eventually blowing the context window. Parity checklist for a custom harness:

Keep raw history append-only and pass the full raw trace to prepare(). Use measured provider token telemetry for measuredInputTokens; do not estimate pressure from characters. For intentional same-instance rebirth/reset, pass hardEpoch: true plus your rendered host seed, or let the package compute the raw seed from history. Persist host-only context such as task rails, file claims, workspace state, chat, and episode cards yourself, then pass those sections into renderRawRebirthSeed() when you need relay-like wake text. Keep clone/model-specific identity deltas out of the stable cached prefix. The Anthropic helper splits the system prompt before ## Your Identity by default; for cheaper clone fanout, put shared seed text before that marker and append per-model deltas after the cached baseline.

Model-aware budgets — context-warp-drive/budget Use the budget resolver when you want Warp Drive tuned to the real model window instead of a one-size-fits-all fold line. It knows common provider/model families (Claude, OpenAI/Codex API, Codex CLI, Gemini, GLM, Grok, Mistral, MiniMax, DeepSeek, Kimi, Qwen) and lets new/unknown models opt in with an explicit measured/configured window. import { resolveContextBudget } from 'context-warp-drive/budget';

const sonnet = resolveContextBudget({ engine: 'claude', model: 'claude-sonnet-4' }); // 200k survival profile: tighter pressure ceiling, hard-epoch-only eviction.

const codexCli = resolveContextBudget({ engine: 'codex', model: 'gpt-5.5' }); // Codex CLI/OAuth path uses its effective 258k input cap, not the Codex API 1M window.

const arbitraryModel = resolveContextBudget({ engine: 'my-provider', model: 'new-million-context-model', contextWindowTokens: 1_000_000, targetBandTokens: 150_000, }); Budget outputs are mechanical ceilings and knobs: contextWindowTokens, messageCeilingTokens, pressureCeilingTokens, prefixSaturationTokens, bandTokens, tailEpochCapTokens, compression profile, and eviction policy. Token pressure uses supplied/measured token telemetry or explicit model windows — it does not infer live token pressure from character counts.

Portable Task Rail — context-warp-drive/task-rail Long-horizon agents need more than memory compression: they need an execution spine that survives folding, rebirth, process restarts, or a custom UI. The Task Rail export is a pure state machine for plan steps, sprint/shoot execution, ACKs, progress, and JSON serialization. It is deliberately not a tool server. No MCP wrapper, no relay persistence, no squad permissions, no chat/Atlas coupling. You own the wrapper: CLI, MCP, browser UI, local JSON, SQLite, or your own agent runtime. import { startTaskRail, sprint, ackStep, shoot, serializeTaskRail, restoreTaskRail, } from 'context-warp-drive/task-rail';

const rail = startTaskRail({ title: 'Ship the feature', objective: 'Keep execution state outside the prompt.', locked: true, step

source