停止总结您的Agent记忆。 每次压缩调用都会消耗一次模型往返，重写您的提示前缀导致提供商提示缓存失效，并静默丢失您的Agent所需的精确标识符。用确定性折叠替代。

在1小时49分钟的代理马拉松中，954次工具调用实现了92.6%的缓存读取命中率。与截断相比成本降低60%，与总结相比降低70%。零额外LLM调用。所有数据均来自提供商用量账本——而非估算。

无限上下文曲速引擎。 让长时函数调用型Agent会话保持在上下文窗口内，无需LLM总结调用，也无需终止会话——同时保持提供商提示缓存热态——并在Agent再次触及已折叠内容时将其自动调回。

确定性。零LLM。纯CPU，零I/O，相同输入产生字节完全相同的输出。提供商无关：支持Anthropic内容块、OpenAI tool_calls 和 Gemini parts。

提取自一个多Agent生产系统，该系统在所有模型和长时Agent工作负载中持续折叠上下文。

• 核心引擎通过380+个确定性测试，覆盖滚动折叠、召回、冻结和集成。
• 以下所有数字均为实测而非估算——来自Claude提供商用量账本的生产缓存率，可实时对Claude复现（ANTHROPIC_API_KEY=… npx tsx examples/benchmark-live.ts，真实模型+真实总结器），也可通过精确的o200k_base BPE token计数离线复现（npx tsx examples/benchmark.ts，确定性，无需API密钥）。

来源说明（点击展开）

此公开包源自生产环境。它是一个运行在私有多Agent系统内部引擎的可移植分发版，因此有意使用通用WARP_*环境变量名、与包无关的示例、原始历史恢复措辞以及工具无关的语音挖掘。字节相同性不变性仅适用于本包——相同输入产生相同折叠视图——并不声称与任何私有集成层具有逐位一致。

---

生产环境实测——真实Claude工作负载，提供商缓存遥测

关键数据来自该引擎驱动的多Agent生产系统——持续在数百回合中运行折叠/冻结引擎的真实Claude工作负载，数据来源于提供商用量账本（缓存读取token ÷ 总输入token）：

生产环境Claude工作负载	实测回合数	缓存读取命中	新输入token	缓存读取输入token
Opus 4.8 agent	691	89.6%	32.9M tok	292.6M tok
Opus agent	510	93.2%	32.6M tok	602.5M tok

在这些高回合数的Claude工作负载中，约90%的输入token从缓存中提供——这正是字节完全相同的冻结折叠前缀在发挥作用，回合复回合，以$0.30/MTok缓存读取代替$3.00/MTok新鲜输入（Sonnet价格）。重新总结式压缩器会重写前缀，永远无法维持此效；截断则滑动窗口并破坏缓存。这就是整个经济论证，实测为证。

范围说明： 上表是单次部署的生产遥测数据，并非对照A/B研究——没有在同一真实工作负载下保留截断或总结对照组进行头对头比较。下面的离线/实时基准测试在小型会话上弥补了这一缺憾；更大规模的受控长期对比研究是未来工作，受限于计算预算，而非机制未经证实。

自行复现——实时对抗Claude

bash ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/benchmark-live.ts # 默认 claude-sonnet-4-6

每回合都有真实的Claude调用，带有Anthropic的cache_control断点、真实的Claude总结器（被告知保留所有标识符——公平竞争），以及提供商自己的cache_read_input_tokens / cache_creation_input_tokens。一个简短的16回合演示低估了生产缓存率（缓存需要≥1024 token的前缀，且CWD的优势在长会话中累积）——但它展示了真实遥测上的机制，CWD从缓存读取，而截断和总结则需重建前缀。

离线确定性演示（无需API密钥，每次运行字节完全相同）

npx tsx examples/benchmark.ts — 一个16回合的故障调试会话，采用精确的o200k_base BPE token计数（一个可移植的代理指标；Claude的分词器不公开），claude-sonnet-4-6列表价格——与上表生产工作负载相同的主力层级，而非廉价演示层级。这相当于CI冒烟测试；总结器是一个透明的确定性替身（它会丢弃超过头部截断范围的标识符——这便是坐标柜要避免的失败模式）。

策略	输入成本	额外LLM调用	事实保留
截断（滚动窗口）	$0.0516	0	44% (7/16)
LLM总结（替身）	$0.0685	6	44% (7/16)
Context Warp Drive	$0.0208	0	94% (15/16)

CWD成本最低（在Claude-sonnet价格下，相比总结降低70%，相比截断降低60%——由于Anthropic的缓存折扣与模型无关，该比率跨层级保持不变），零额外模型调用，并在保留率上显著优于截断。（一个经过良好提示的真实总结器可以以更高成本匹配保留率——CWD的持久优势在于成本 + 零调用 + 确定性 + 热缓存。）该引擎与提供商无关：设置WARP_BENCH_MODEL（以及未列出模型的WARP_BENCH_PRICE_*），即可针对任何模型进行基准测试，包括OpenAI或更便宜的Claude层级。

与基于LLM的记忆工具对比

	Context Warp Drive	Mem0	Letta (MemGPT)	Zep (Graphiti)
方法	确定性折叠	LLM提取+向量数据库	LLM管理的三层记忆	LLM提取+知识图谱
额外LLM调用	0	每次记忆操作	每次记忆决策	每次实体提取
提示缓存影响	保持热态（字节相同前缀）	失效（重写前缀）	失效	失效
运行时依赖	零（核心引擎）	需要向量数据库	完整Agent运行时替代	Neo4j + LLM + 嵌入
提供商支持	Anthropic · OpenAI · Gemini	多平台（SDK封装）	仅Python	仅Python
许可证	MIT	Apache 2.0	Apache 2.0	Apache 2.0

每个受资助的竞品都使用LLM调用来提取、总结或管理记忆。Context Warp Drive 是唯一的确定性方法——零模型调用、零延迟、零缓存失效。

---

bash git clone https://github.com/dogtorjonah/context-warp-drive.git cd context-warp-drive && npm install npx tsx examples/benchmark.ts # 无需API密钥——确定性，每次运行字节完全相同

要运行含有真实Claude调用和提供商缓存遥测的实时基准测试： bash ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/benchmark-live.ts

---

每个长Agent会话都会撞上同一堵墙：上下文窗口被填满。通常的解决之道都很糟糕：

• 截断丢弃历史对话的中间部分——Agent忘记了自己正在做什么。
• LLM总结（“压缩”）消耗一次模型调用、增加延迟、非确定性，而且每次重写前缀都会破坏您的提供商提示缓存。

Context Warp Drive 两者都不采用。它确定性地折叠旧回合为紧凑的结构骨架（每行工具调用 + 保留推理），在预算评分的坐标柜中保存显著的精确标识符（UUID、SHA、路径、端口），冻结已折叠前缀以在缓存温热时字节完全相同地重用，并在Agent再次触碰某路径时自动调回已折叠内容。无模型调用。无截断。缓存保持热态。

---

尚未发布到 npm。请从源码安装： bash git clone https://github.com/dogtorjonah/context-warp-drive.git cd context-warp-drive npm install # 运行 prepare -> 自动构建到 dist/

可选——仅用于参考SQLite情节存储：

npm install better-sqlite3

核心 (context-warp-drive/fold) 零运行时依赖。better-sqlite3 仅为参考式情节存储所需的可选同级依赖。

本地 tarball / 将来 npm 安装

dist/ 被 gitignore，因此在其他项目中使用前需先构建。安装本地包： bash npm run build # 显式回退 npm pack

在你的消费项目中：

npm install /path/to/context-warp-drive/context-warp-drive-*.tgz

首次 npm 发布后，安装命令为： bash npm install context-warp-drive

---

如果让 AI 帮你接入

请粘贴以下内容：

从源码检出或本地 tarball 添加 context-warp-drive，然后在每次模型调用前用 FoldSession.prepare() 包裹我们的函数调用消息历史。单独保存原始历史；只将准备好的 messages 视图发送给提供商。使用 cacheHot 和 stats 记录日志。

然后添加提供商缓存配置：

提供商	操作
Claude / Anthropic	使用 context-warp-drive/providers/anthropic 中的 prepareAnthropicCachedRequest()，传入 messages、sealedBoundary、system 和 tools。它会标记中继式断点：工具、稳定的系统头部、封装的折叠/重生边界和滚动尾部。默认 TTL 为 Anthropic 的 5 分钟缓存形态；仅当需要付费的 1 小时缓存时传递 ttl: '1h'，并将返回的 requestOptions/anthropicBeta 合并到你的 SDK 或 fetch 调用中。记录 usage.cache_read_input_tokens 和 usage.cache_creation_input_tokens。
OpenAI	无需缓存标记。保持静态的工具/系统/上下文在前，传入准备好的 messages，可选地重用稳定的 prompt_cache_key，并记录 usage.prompt_tokens_details.cached_tokens。
Gemini	Gemini 2.5+ 在前缀匹配时自动使用隐式缓存。对于大型静态文档/语料库，可以单独创建显式 Gemini 缓存并将其作为 cachedContent 传递；在此稳定前缀之后保持折叠对话。记录 usage_metadata。
Gemini CLI	使用 context-warp-drive/providers/gemini-cli 来折叠 CLI 拥有的 JSONL 视图，保留元数据头部，并使用 $set.messages + $set.lastUpdated 进行重写。
Codex CLI	使用 context-warp-drive/providers/codex-cli 从规范转录行中重建一个折叠的 Responses 项目种子，用于 thread/inject_items。
Claude Code CLI	使用 context-warp-drive/providers/claude-cli 构建折叠的 Claude Code JSONL 链，并在运行 claude --resume 之前原子地重写 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl。

Context Warp Drive 保持前缀字节完全相同。提供商 SDK 调用仍控制提供商特定的缓存设置。

---

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

// 每个对话一个实例。折叠超出活动窗口的内容并保持提供商缓存热态。 const session = new FoldSession();

// 你的完整提供商形式的消息历史（Anthropic / OpenAI / Gemini 消息对象）。 const history = [ { role: 'user', content: '调查 src/parser.ts 中失败的测试' }, // ... 每回合增长 ... ];

// 每次调用模型之前： const { messages, cacheHot, stats } = session.prepare(history, { // 可选但推荐：传递上一回合的提供商/中继输入token遥测数据。 // 默认在 240k token 时，FoldSession 会强制开始新的折叠纪元， // 而不是向超大提示中热重用。 measuredInputTokens: previousUsage?.input_tokens, });

// messages 是待发送的压缩视图。当 cacheHot 为 true 时，前缀 // 与上一回合字节完全相同，因此提供商提示缓存被复用。 await callYourModel(messages); // Anthropic / OpenAI / Gemini — 消息结构不变 console.log(发送 ${messages.length} 条消息 · cacheHot=${cacheHot} · 节省=${stats.savingsPercent ?? 0}%);

这就是全部核心。想要持续瘦身折叠，传入 ALWAYS_ON_FOLD_CONFIG；要匹配你提供商的真实缓存 TTL，设置 freeze: { enabled: true, ttlMs: 3_600_000, maxTailChars: 150_000 }。测量token压力防护默认使用 DEFAULT_FOLD_PRESSURE_CEILING_TOKENS (240,000)；传入 pressureCeiling: false 禁用，或 pressureCeiling: 120_000 调优。

参见 examples/anthropic-loop.ts 和 examples/openai-loop.ts 获取完整工具循环示例。

---

硬纪元重生种子对等

FoldSession.prepare() 包含了 Voxxo 中继使用的便携式硬纪元路径：它用一条确定性的重生种子消息替换提供商可见视图，将触发的实时用户回合合并精确一次，并将该压缩种子重新封装为下一个冻结前缀。当实测输入 token 达到 pressureCeiling 时自动触发；工具也可以直接强制走相同路径： typescript const outcome = session.prepare(history, { hardEpoch: t

Stop summarizing your agent's memory. Every compaction call burns a model round-trip, rewrites your prefix so the provider prompt cache goes cold, and quietly drops 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. −60% cost vs truncation, −70% vs summarization. Zero extra LLM calls. Every number measured from the provider's own usage ledger — not estimated.

The Infinite Context Warp Engine. Keep long function-calling agent sessions under the context window without LLM summarization calls and without ending the session — while keeping provider prompt caches hot — and page folded content back in the moment the agent touches it again.

Deterministic. Zero-LLM. Pure CPU, zero I/O, byte-identical output for identical inputs. Provider-agnostic: Anthropic content blocks, OpenAI tool_calls, and Gemini parts.

Extracted from a production multi-agent system, where it folds context continuously across every model and long-running agent workloads.

• The core engine passes 380+ deterministic tests across rolling fold, recall, freeze, and integration.
• Every number below is measured, not estimated — production cache rates from the Claude provider usage ledger, reproducible live against Claude (ANTHROPIC_API_KEY=… npx tsx examples/benchmark-live.ts, real model + real summarizer) and offline with exact o200k_base BPE token counts (npx tsx examples/benchmark.ts, deterministic, no key).

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.

---

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). A re-summarizing compactor rewrites the prefix and can never sustain this; truncation slides the window and breaks it. This is the entire economic argument, measured live.

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.0208	0	94% (15/16)

CWD is cheapest (−70% vs summarization, −60% vs truncation at Claude-sonnet rates — the ratio holds across tiers since Anthropic's cache discount is model-invariant), makes zero extra model calls, and beats truncation decisively on retention. (A well-prompted real summarizer can match retention at higher cost — CWD's durable edge is cost + zero calls + determinism + a hot cache.) 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 (MemGPT) | Zep (Graphiti)
---|---|---|---|---
Approach | Deterministic fold | LLM extraction + vector DB | LLM-managed 3-tier memory | LLM extraction + knowledge graph
Extra LLM calls | 0 | Per memory operation | Per memory decision | Per entity extraction
Prompt cache impact | Stays hot (byte-identical prefix) | Invalidated (rewritten prefix) | Invalidated | Invalidated
Runtime deps | Zero (core engine) | Vector DB required | Full agent runtime replacement | Neo4j + LLM + embeddings
Provider support | Anthropic · OpenAI · Gemini | Multi (SDK wrappers) | Python only | Python only
License | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0

Every funded competitor uses LLM calls to extract, summarize, or manage memory. Context Warp Drive is the only deterministic approach — zero model calls, zero latency, zero cache invalidation.

---

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

---

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

• Truncation drops the middle of your history — the agent forgets what it was doing.
• LLM summarization ("compaction") costs a model call, adds latency, is non-deterministic, and busts your provider prompt cache every time it rewrites the prefix.

Context Warp Drive does neither. It deterministically folds old turns into compact structural skeletons (one line per tool call + retained reasoning), conserves the salient exact identifiers (UUIDs, SHAs, paths, ports) in a budget-scored Coordinate Closet, freezes the folded prefix so it's reused byte-identical while the provider cache is warm, and pages folded content back in automatically when the agent re-touches a path. No model calls. No truncation. Cache stays hot.

---

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:
npm install better-sqlite3

The core (context-warp-drive/fold) has zero runtime dependencies. better-sqlite3 is an optional peer needed only by the reference episodic 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:
npm install /path/to/context-warp-drive/context-warp-drive-*.tgz

After the first npm publish, installation becomes:

npm install context-warp-drive

---

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	No cache marker is required. Keep static tools/system/context first, pass the prepared messages, optionally reuse a stable prompt_cache_key, and log usage.prompt_tokens_details.cached_tokens.
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 the prefix byte-identical. The provider SDK call still owns provider-specific cache settings.

---

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

// One per conversation. Folds past the active window + keeps the provider cache hot.
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 240k 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 (240,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,
);

Bounded is what makes it boundless. A hard epoch collapses the provider-visible view to one compact seed message — it does not discard anything. The raw transcript remains recall backing: fold recall (§4 below) keeps paging folded/pre-epoch content back in the moment the agent re-touches a path, a claim, or a prior identifier, exactly as it does for an ordinary rolling fold. That's the actual mechanism behind "long-horizon": the window itself never grows past its ceiling, so it stays cheap and cache-friendly turn after turn, while forward momentum — what the agent was doing, what it touched, what it decided — survives the reset 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, full-recompute-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,
  steps: [
    { instruction: 'Inspect the failing path.' },
    { instruction: 'Patch the smallest correct surface.' },
    { instruction: 'Validate and write the handoff.' },
  ],
});

const batch = sprint(rail, { sprintCount: 2 });
ackStep(rail, batch.steps![0].id, 'done', { evidence: 'source read' });
const next = shoot(rail);

const saved = JSON.stringify(serializeTaskRail(rail));
const restored = restoreTaskRail(JSON.parse(saved));

Pair it with FoldSession like this: raw transcript stays in your storage, folded prompt view stays lean, and task rail tracks what the agent is supposed to do next.

Draft operations (TASK_RAIL_DRAFT_OPERATIONS, TaskRailDraft, conflict/merge types) are exported for parity with the full-featured relay wrapper. The draft types are here; the merge engine lives in the relay-side wrapper. If you need collaborative draft merging, build it on the exported types — the pure state machine only handles locked-rail execution.

See examples/task-rail.ts for a full runnable walkthrough (start → sprint → ack → shoot → serialize → restore, zero dependencies).

Raw rebirth seed — context-warp-drive/raw-rebirth-seed

When a long-running agent chooses a hard epoch, it needs a deterministic wake seed that is computed from the trace, not summarized by a model. The raw rebirth seed renderer exposes that package shape directly: Last User + AI Messages, Current Thread, Raw Trace Coordinate Closet, Active Edit Delta, Task Rail, Activity Log, workspace context, and the orientation footer, with the same default section budgets and allocation priority used by the relay-style hard epoch.

import { buildRawRebirthSeedFromMessages } from 'context-warp-drive/raw-rebirth-seed';

const seed = buildRawRebirthSeedFromMessages(history, {
  predecessorName: 'agent-before-reset',
  includeTrailingUserTurn: false,
  workspaceContext: {
    currentCwd: process.cwd(),
    currentWorkspace: 'my-agent-runtime',
  },
});

FoldSession uses this renderer automatically when a pressure hard epoch fires and you do not pass hardEpochSeed. If your host has richer trace sections, call renderRawRebirthSeed() and pass those strings explicitly. See docs/raw-rebirth-seed.md for exact parity boundaries and copy-paste examples.

---

1. Rolling fold (page-out) — foldContext

From the active window backward, every prior turn skeletonizes into one line per tool call ($ cmd → ok, read path, …) plus budgeted retained reasoning. Only the newest turns stay at full fidelity. The fold is a synthetic user+assistant pair with a self-documenting preamble; it never mutates your raw history (it returns a view).

"Turn" is looser than it sounds — long agentic work folds per step, not per user message. A conversational turn only ends at real user text (isUserTurnBoundary); a long single-prompt agentic rail — one kickoff, hundreds of tool-call steps, no further user text — is structurally ONE turn. planActiveTurnStepFold detects that marathon pattern and re-segments the oversized active turn at agentic-step boundaries (each assistant tool-call + its result), so foldContext can skeletonize the OLD steps of a still-open turn while the newest N steps stay full-fidelity. This is what keeps a long-horizon single-turn agent session bounded without waiting for a user message that may never come.

2. Coordinate Closet — exact-value conservation

Folded turns are skeletonized, but their exact identifiers are not paraphrased. nominateVerbatim extracts UUIDs, long hashes, absolute paths, digit-bearing key/values (port=3002), and issue refs, and conserves them in a Coordinate Closet (conserved from folded turns): … block. Opaque ids carry a deterministic context label (7fd5835b ⟦changelog_id⟧). A separate capped lane conserves identifiers from operator-pasted user text too.

3. Fold freeze (cache-hot reuse) — evaluateFoldFreeze

The folded prefix is frozen and reused byte-identical between epochs, so new turns just append to the raw tail and the provider prompt cache stays warm. It only recomputes at an epoch: first call, cold TTL gap, raw-tail cap exceeded, a thinning/claim change, or a boundary rewrite. Maximizing the hot-reuse ratio is the entire point of deterministic folding — a re-summarizing compactor can never do this.

4. Fold recall (ambient page-in) — buildFoldRecallContext

A page table (buildFoldIndex) tracks everything the fold paged out. When activity proves relevance — you touch a path again, or claim a file — the folded content pages back in as a budgeted recall card, appended append-only onto the freeze tail (cache stays hot) and re-folded at the next epoch. Fully cyclic, with residency TTLs so cards don't thrash.

5. Episodic recall (durable cross-session memory) — context-warp-drive/episodes

Beyond the in-session fold, sealed work episodes (the files touched + the agent's verbatim conclusions) persist to a local store and are recalled by path the next time any session touches a member file. Turnkey portable store included (createEpisodeStore, SQLite); the advanced chain-card/narration engine ships namespaced as richEpisodes.

6. Glyph grammar (register tags) — context-warp-drive/glyphs

Every agent message opens with one register glyph — 🔍 in-progress · ▶ executing · 🏁 verdict · ⚠️ hazard · ❓ blocked. parseRegisterGlyph classifies it; episodic recall uses it as a trust signal so only settled conclusions (🏁/⚠️) get harvested into durable memory while transient work (🔍/▶/❓) self-excludes. See docs/glyph-grammar.md.

7. Context budget (model-aware mechanical limits) — context-warp-drive/budget

The budget resolver turns model/engine/window choices into deterministic fold knobs: active band, message ceiling, pressure ceiling, prefix saturation, tail epoch cap, and compression/eviction profile. Known model tables cover common providers, while explicit contextWindowTokens lets any new model opt in without waiting for a package release.

8. Task Rail (portable execution state) — context-warp-drive/task-rail

Task Rail is the dependency-free long-horizon execution state machine. It tracks steps, sprint/shoot reservations, ACK status, progress, and JSON serialization so your own tool/UI/storage can preserve “what next?” outside the provider prompt.

---

Provider-agnostic by design

The engine reads three message shapes natively — pass your history through unchanged:

Provider	Shape
Anthropic	`{ role, content: string
OpenAI (+ DeepSeek, Kimi, GLM, Mistral, Grok, MiniMax)	{ role, content, tool_calls } + { role: 'tool', tool_call_id }
Gemini	{ role: 'model', parts: [...] } with functionCall / functionResponse

FC APIs and supported CLI transports. Context Warp Drive folds the conversational message array you control directly. For CLI/agent runtimes that own their own context, use the dedicated provider packs below.

CLI fold packs mirror the Voxxo relay seams for owned-history runtimes: context-warp-drive/providers/gemini-cli rewrites Gemini CLI JSONL $set.messages, context-warp-drive/providers/codex-cli emits folded Responses items for thread/inject_items, and context-warp-drive/providers/claude-cli builds and writes a uuid-linked Claude Code JSONL chain for claude --resume.

For Claude Code, the runnable setup layer is context-warp-drive/host/claude-cli-loop. It spawns claude --print --input-format stream-json --output-format stream-json, learns the session id from the stream, tracks Anthropic-reported usage tokens, computes tail vs hard-epoch folds, atomically rewrites the Claude Code project JSONL, and respawns with --resume <session-id>. Use mode: 'dry-run' to write a <session>.jsonl.dryrun sidecar before letting it touch the live file.

npx tsx examples/claude-cli-loop.ts /path/to/project
WARP_CLAUDE_CLI_FOLD=dry-run npx tsx examples/claude-cli-loop.ts

If you want the normal Claude Code terminal UI instead of --print, use context-warp-drive/host/claude-tmux-loop. It starts plain interactive claude inside tmux, gives you an attach command, tails ~/.claude/projects/.../<session>.jsonl, folds from provider-measured usage, rewrites the JSONL, and restarts the tmux session with --resume.

npx tsx examples/claude-tmux-loop.ts /path/to/project
WARP_CLAUDE_TMUX_FOLD=dry-run npx tsx examples/claude-tmux-loop.ts

---

// Core fold engine (zero deps) — also at "context-warp-drive/fold"
import {
  FoldSession,           // the orchestrator (fold + freeze)
  DEFAULT_FOLD_PRESSURE_CEILING_TOKENS,
  foldContext,           // rolling fold (page-out)
  ALWAYS_ON_FOLD_CONFIG, DEFAULT_FOLD_CONFIG, type FoldConfig, type FoldMessage, type FoldResult,
  evaluateFoldFreeze, commitFoldFreeze, createFoldFreezeState, // freeze layer
  buildFoldIndex, extractRecallSignals, buildFoldRecallContext, // recall layer
  nominateVerbatim, detectTurns,
} from 'context-warp-drive';

// Episodic recall — also at "context-warp-drive/episodes"
import {
  deriveEpisodesFromMessages, recordEpisodes, recallEpisodeCards, // portable store
  createEpisodeStore,                                              // SQLite reference (needs better-sqlite3)
  richEpisodes,                                                    // advanced chain-card engine (namespaced)
} from 'context-warp-drive';

// Glyph grammar — also at "context-warp-drive/glyphs"
import { parseRegisterGlyph, REGISTER_GLYPHS, classifyAssistantRegister } from 'context-warp-drive';

// Model-aware fold/pressure knobs — also at "context-warp-drive/budget"
import { resolveContextBudget } from 'context-warp-drive';

// Portable execution state — also at "context-warp-drive/task-rail"
import { startTaskRail, sprint, shoot, ackStep, serializeTaskRail } from 'context-warp-drive';

// Gemini CLI JSONL folding adapter
import {
  buildGeminiCliFoldView,
  readLatestGeminiCliMeasuredTokens,
  writeFoldedGeminiCliJsonl,
} from 'context-warp-drive/providers/gemini-cli';

// Codex CLI fold seed for thread/inject_items
import { buildCodexFoldItems } from 'context-warp-drive/providers/codex-cli';

// Claude Code CLI JSONL folding adapter
import {
  buildClaudeCliFold,
  writeFoldedClaudeCliJsonl,
} from 'context-warp-drive/providers/claude-cli';

// Claude Code CLI setup loop: spawn, monitor measured usage, fold, rewrite, resume
import { ClaudeCliFoldLoop } from 'context-warp-drive/host/claude-cli-loop';

// Claude Code interactive tmux loop: normal terminal UI, JSONL tail, fold, resume
import { ClaudeTmuxFoldLoop } from 'context-warp-drive/host/claude-tmux-loop';

Claude Code CLI setup loop

import { ClaudeCliFoldLoop } from 'context-warp-drive/host/claude-cli-loop';

const loop = new ClaudeCliFoldLoop({
  cwd: process.cwd(),
  sessionId: process.env.CLAUDE_SESSION_ID, // optional; learned from stream-json when omitted
  model: process.env.CLAUDE_MODEL ?? 'claude-sonnet-4-6',
  mode: process.env.WARP_CLAUDE_CLI_FOLD === 'dry-run' ? 'dry-run' : 'on',
  authMode: process.env.CLAUDE_CODE_OAUTH_TOKEN ? 'oauth' : 'inherit',
  onEpoch: (epoch) => console.error(epoch.reason),
});

await loop.start();
await loop.sendUserText('Continue the current task.');

The loop only folds from provider-measured usage telemetry. If you already keep your own canonical transcript, pass transcript: async () => rows and captureTranscript: false; otherwise the loop captures user text, assistant text, tool calls, and tool results from Claude Code's stream-json events.

Claude Code interactive tmux loop

import { ClaudeTmuxFoldLoop } from 'context-warp-drive/host/claude-tmux-loop';

const loop = new ClaudeTmuxFoldLoop({
  cwd: process.cwd(),
  sessionId: process.env.CLAUDE_SESSION_ID, // optional; otherwise discovered from JSONL
  model: process.env.CLAUDE_MODEL ?? 'claude-sonnet-4-6',
  mode: process.env.WARP_CLAUDE_TMUX_FOLD === 'dry-run' ? 'dry-run' : 'on',
  authMode: process.env.CLAUDE_CODE_OAUTH_TOKEN ? 'oauth' : 'inherit',
  onSpawn: (info) => console.error(info.attachCommand),
});

await loop.start();

This loop does not pass --print; the user attaches to tmux and uses Claude Code normally. Context Warp observes the on-disk JSONL transcript, so an unwrapped Claude process can still be observed by your own code, but automatic kill/rewrite resume requires the wrapper to own the tmux session.

---

All optional; sensible defaults. WARP_FOLD_FREEZE (freeze on/off) · WARP_FOLD_FREEZE_TTL_MS · WARP_FOLD_FREEZE_MAX_TAIL_CHARS · WARP_FOLD_RECALL · WARP_FOLD_RECALL_MAX_CARDS · WARP_FOLD_RECALL_VERBATIM · WARP_FOLD_TARGET_BAND_TOKENS · WARP_FOLD_TRIGGER_TOKENS · WARP_FOLD_EPISODES_*. Full table in docs/context-folding.md §8.

---

• docs/context-folding.md — the authoritative engine reference (what folds, Coordinate Closet, freeze epochs, recall, episodic, env switches, source map).

• docs/architecture.md — how the layers compose and how to wire them into any FC loop.

• docs/glyph-grammar.md — the register-glyph contract and why it powers episodic narration.

  npm test # runs the 380+ test deterministic suite (rolling fold, freeze, recall, task rail)

JonahT © Jonah Tarashansky