RACS (Remote Agent Context Store) plans provider-faithful prefix-cache directives for Massive Intelligence (IM) agents without ever calling a provider API. Declare the prompt as segments; RACS lints the layout for the documented cache-killers, emits the exact directive your provider understands, schedules keep-warm refreshes, detects prefix drift, and reports savings in your own pricing. Zero credentials, zero network, the host stays in control.
pnpm add @takk/racsPrefix caching fails in production for boring reasons: a timestamp in the system prompt, a tool list that reorders itself, a layout that puts the volatile part first. An OpenClaw issue measured ten times the expected cost from exactly that failure mode. RACS makes each of these a planned, linted, measured decision.
Nine lint codes catch the documented cache-killers before they bill you: timestamps and identifiers in
segments declared stable, volatile-early layouts, unstable tool definitions, below-minimum prefixes,
write-premium traps. Errors defeat caching, warnings cost money, and racs analyze exits
nonzero in CI.
The silent cache-bust class of incident becomes a failed build instead of a surprise on the invoice.
One plan() call resolves the provider profile and emits the directive that provider
actually understands, across four adapter families: breakpoint (cache_control,
cachePoint), routing-key (prompt_cache_key), resource
(cachedContents), and passive (ordering advice only). Deterministic FNV-1a 64 prefix keys
and break-even math come with every plan.
16 providers, 4 code paths, zero per-provider conditionals in your application.
Feed it the usage counts your provider already returns and it normalizes them into hit ratios, read and write token totals, and USD savings, computed strictly from pricing you supply. RACS never hardcodes a provider price.
One stats() call answers the question finance actually asks: what did
caching save this month, net of write premiums.
Every plan fingerprints its stable segments. When the same agent lineage produces a different prefix key, the drift report names exactly which segments changed and how many cached tokens died with the change.
A one-byte edit to a "stable" prompt is caught on the next plan, not three invoices later.
Provider caches expire on a TTL; a touch shortly before expiry keeps them warm at read price instead of
paying the write premium again. schedule() computes the due moments at 90 percent of each
window; the host runs the timer and the call.
Keep-warm stops being a hand-rolled heartbeat script and becomes a library primitive.
RACS never calls a provider API. It holds zero credentials, opens zero network connections, and never sends a byte anywhere. Planning and accounting are synchronous and in-process; the host applies every directive and makes every call itself.
Nothing new to audit: no credential to store, no egress path to review, no vendor in the request loop.
Providers disagree on cache semantics: Anthropic wants explicit breakpoints, OpenAI caches automatically behind routing keys with no write counter, Gemini sells the cache as a server-side resource with storage economics. RACS models each provider as a thin profile over one of four adapter families, and every profile value is overridable per engine instance.
The caller marks cache boundaries inside the request body, up to 4 per request, with 5m and 1h TTL tiers. Writes cost 1.25x base input on the 5m tier and 2x on the 1h tier; cached reads cost 0.1x. Plans place the breakpoints and prove they pay back.
The provider caches server-side; the caller can only steer routing with a key so identical prefixes land on the same cache. No write premium, reads around 0.25x, optional 24h retention. Plans emit the sticky key and the layout that makes it hit.
The cache is created, refreshed, and deleted by the host, with caller-set TTL and per-token-hour storage billing. Plans emit the full lifecycle: create, read, refresh, delete, plus the storage economics that decide whether the resource is worth keeping.
The provider caches automatically and exposes no controls. RACS still orders segments stable-first, lints the layout, and accounts usage, because on a left-anchored cache the ordering itself is the optimization.
cache_control, 4 breakpoints, 5m and 1h TTLs, 0.1x reads
cachePoint on the Converse API, Anthropic-equivalent semantics
Hermes Agent system_and_3 layout over cache_control semantics
Claude on Microsoft Foundry honors cache_control unchanged
prompt_cache_key, 128-token increments, optional 24h retention
x-grok-conv-id and prompt_cache_key, reads around 0.16x
64-token cache blocks, prompt_cache_key routing, 0.1x reads
Kimi platform caching through the OpenAI-compatible surface
cache_control passthrough and cached_tokens across upstreams
cachedContents lifecycle, caller-set TTL, storage per token-hour
automatic on gpt-oss models, entries expire after 2 hours idle
disk-based context cache, hit and miss token reporting, 0.1x reads
local runtime KV reuse, analytics measure latency, not billing
local runtime KV reuse, same posture as ollama
no public prefix-cache controls as of June 2026, ordering still plans
extensible: define your own profile via options.profiles, any family
pnpm add @takk/racsnpm install @takk/racsyarn add @takk/racsbun add @takk/racsZero runtime dependencies. No peer dependencies. The tarball is 46 files; the core entry is 10.72 kB brotli.
import { createRACS } from '@takk/racs';
const racs = createRACS({
pricing: {
// your prices, USD per million tokens; RACS never hardcodes them
'claude-sonnet-4-5': { inputPerMTok: 3, cacheReadPerMTok: 0.3, cacheWrite5mPerMTok: 3.75 },
},
});
const plan = racs.plan({
agentId: 'support-agent',
provider: 'anthropic',
model: 'claude-sonnet-4-5',
segments: [
{ id: 'system', role: 'system', stability: 'stable', content: SYSTEM_PROMPT },
{ id: 'tools', role: 'tools', stability: 'stable', content: TOOL_DEFINITIONS },
{ id: 'turn', role: 'dynamic', stability: 'volatile', content: userMessage },
],
reuse: { intervalSeconds: 45 },
});
plan.directives; // provider-faithful: cache_control breakpoints, in order
plan.findings; // lint findings; errors mean the layout defeats caching
plan.breakEven; // write premium vs read savings, stated in tokens// after the provider call, report the counts the response already carries
racs.record({
provider: 'anthropic',
model: 'claude-sonnet-4-5',
prefixKey: plan.prefixKey,
inputTokens: 5200,
cacheReadTokens: 4100,
});
racs.stats(); // hit ratio, read/write tokens, USD saved, net of premiums
// keep-warm: entries come due at 90 percent of each TTL window
for (const entry of racs.schedule()) {
// the host touches the cache (a cheap read), then reports it
racs.markRefreshed(entry.prefixKey);
}The racs binary ships in the box: help, version,
analyze for CI gating, simulate for the deterministic demonstration below,
inspect --watch for live state, and serve, a hardened local HTTP bridge exposing
/plan, /lint, /usage, /stats, /schedule,
/refreshed, and /invalidate to non-JavaScript stacks.
$ racs simulate --calls 400 --seed 7
racs simulate: 400 calls, seed 7, interval 60s, provider anthropic
structured lint: clean
naive lint:
LINT warning segment-order naive-turn Volatile segment 'naive-turn' precedes stable segment 'naive-tools'. Prefix caches are left-anchored, so every token after 'naive-turn' is unreachable for the cache. [...]
LINT warning timestamp-in-stable naive-system Segment 'naive-system' is declared stable but contains an ISO-8601 datetime (digest 9d6f8366), and the words 'today' or 'current time' near digits. [...]
drift naive: 217dbd595cc63a93 -> 7dfee9d9ed5102b9, segments [naive-system], 3000 tokens invalidated (call 2)
drift naive: 7dfee9d9ed5102b9 -> 44338bff92d176f9, segments [naive-system], 3000 tokens invalidated (call 3)
[... 400 lines hidden: 397 further drift reports (calls 4 through 400) and the progress lines at calls 100, 200, and 300 ...]
progress: 400/400 calls, structured hits 399, naive hits 0
--- summary ---
calls: 400
structured: hit ratio 0.96, net savings 9.87 USD
naive: hit ratio 0.00, write-premium loss 1.50 USD
structured prompt saves $11.37 (88.1%) versus naive
Output of racs simulate --calls 400 --seed 7 against the shipped demonstration pricing,
truncated for length. Same seed, same output, every time: the simulation is fully deterministic.
Measured agent workloads report 41 to 80 percent savings on input spend from prefix caching (arXiv 2601.06007, January 2026). Your number depends on three quantities you already know. Estimate it from the provider multipliers.
Estimated monthly savings
$333.00
33.3% of input spend
Resource family: Google additionally bills cachedContents storage per token-hour, not modeled here. Keep the TTL as short as your reuse interval allows.
Negative estimate: at this hit ratio the write premium exceeds the read savings. This exact situation is the write-premium-trap lint; raise the hit ratio or do not cache.
An estimate from the provider multipliers and your own numbers, nothing more.
Server-side truth comes from usage reports: record real calls with record() and read
stats().
Sizes are brotli-compressed, measured on the published build and enforced in CI by size-limit.
The full engine: plan, lint, record, stats,
schedule, markRefreshed, drifts, invalidate,
profileOf, on, flush, close, plus the memory, file,
and KV-style state backends.
GenAI span ingestion: maps OpenTelemetry GenAI semantic-convention spans into normalized usage records, so traces you already collect feed the ledger without new instrumentation.
Middleware for the Vercel AI SDK: applies plan directives through providerOptions and
records usage from results, streaming included via wrapStream.
Bridges to the four sibling packages: freeze parameter tuning while the prefix drifts and release after 3 stable plans, observe the cache behaviorally, plan per routed model, invalidate on credential rotation.
The same engine without the Node file backend, so browser bundles never advertise a backend they cannot
run. Pair with kvState for persistence.
Edge-runtime entry with the identical surface. kvState wraps any Redis, Upstash, or
Cloudflare KV style client in one line for cross-isolate state.
analyze gates prompt changes in CI, inspect --watch redraws live state, and
serve is a hardened, token-authenticated HTTP bridge for non-JavaScript stacks.
Planner, PrefixAnalyzer, Ledger, PROVIDER_PROFILES,
fnv1a64, and estimateTokens are all public exports; build your own pipeline
from the same parts the engine uses.
plan.created, prefix.drifted, usage.recorded,
refresh.due, resource.action, limit.reached: synchronous,
deterministic under an injected clock, and free of any telemetry vendor.
Each package stands alone with zero runtime dependencies; together they cover credentials, routing,
behavior, tuning, and caching. The /integrations entry bridges them in one line each.
Credential rotation, failover, and circuit breaking for provider API keys; RACS invalidates cached
resources when a key rotates, via keymeshBridge.
Model routing and fallback chains across providers; modelchainBridge plans a cache layout
for whichever model the chain routes to.
Behavioral observation for agent systems; behavioralaiBridge turns the cache into a
behaviorally observed surface, hit and drift patterns included.
Adaptive runtime parameter tuning with canary rollouts and rollback; noeticosBridge
freezes tuning while the prefix drifts and releases it after 3 stable plans.
Prefix-cache management: stability linting, provider-faithful directives, drift detection, keep-warm scheduling, savings analytics.
davccavalcante/racsYes. 187 tests across 13 suites pass on Node 22 and Node 24, with coverage at 92.46 percent statements, 82.09 percent branches, 93.33 percent functions, and 92.49 percent lines. TypeScript strict mode, lint, and package checks are clean, and every release ships with SLSA provenance.
Never. RACS plans directives, lints layouts, schedules refreshes, and accounts usage entirely in-process. It holds zero credentials and opens zero network connections; the host application stays in control of every provider call and applies the directives itself.
A gateway sits on the wire and forwards traffic. RACS is a planning engine: it computes the cache directives your existing client applies on its own requests. As of June 2026 we found no shipping npm package that combines stability linting, multi-provider directive planning, drift detection, persistence, and savings analytics in one library.
16 profiles over 4 adapter families. Breakpoint: anthropic, bedrock, hermes, microsoft-foundry. Routing-key: openai, xai, mistral, moonshot, openrouter. Resource: google. Passive: groq, deepseek, ollama, lmstudio, huggingface, custom. Every profile value is overridable per engine instance, so a provider changing terms is a configuration edit, not a release.
Measured agent workloads report 41 to 80 percent savings on input spend (arXiv 2601.06007, January 2026). Your number depends on prefix share, hit ratio, and the provider multipliers; the calculator on this page estimates it from your own figures, and the ledger reports the measured truth once you record real usage.
The documented production cache-killers: timestamps and identifiers inside segments declared stable, volatile content placed early in the prompt, unstable tool definitions, prefixes below the provider minimum, breakpoints placed after volatile segments, write-premium traps, wrong segment ordering, and missing stability declarations.
Only if you pass it. Every segment accepts a contentHash instead of content. In hash-only mode RACS never sees the text, and plans, drift reports, persisted snapshots, and telemetry carry hashes and token counts only.
Every plan fingerprints its stable segments with deterministic FNV-1a 64 hashing. When a later plan for the same agent lineage produces a different prefix key, RACS emits a drift report naming exactly which segments changed and how many cached tokens were invalidated.
In memory by default. The file backend persists snapshots on Node, and kvState wraps any Redis, Upstash, or Cloudflare KV style client in one line. Persistence is optional; the engine is fully functional without it.
From pricing you supply. RACS never hardcodes provider prices: you pass a table in USD per million tokens, and the ledger combines it with normalized usage reports into hit ratios, savings, and net effect after write premiums. Without a pricing table, every statistic is still reported in tokens.