ReasonCACHE
without weight updates
A learned prefix cache that distills demonstrations into layer-wise KV prefixes, keeping the backbone frozen while teaching the model reusable reasoning behavior.
The paper assumes reasoning traces already exist. Our separate Learned Prefix Cache page covers the shared Cartridges plus ReasonCACHE architecture and the Active Reading induction bridge.
Reasoning skill in a cache, not in the weights.
The paper positions ReasonCACHE as a middle path between in-context learning and in-weight learning: optimize a compact KV prefix, keep the pretrained model frozen, and avoid long demonstration prompts at inference.
ReasonCACHE wins on the axes that matter for serving
The paper argues for a three-way efficiency gain: data, inference compute, and trainable parameter count.
Why this matters to KNLP
Cartridges already made the case that learned KV state can be a deployable primitive for document-grounded inference. ReasonCACHE shifts the target: the cache is no longer just a compressed document. It is a trained reasoning interface.
It learns the cache directly.
ReasonCACHE uses prefix tuning specialized to reasoning. At every transformer layer, learned key and value vectors are prepended to the token-derived KV cache.
trainable: P_K, P_V frozen: model weights
More exemplar tokens
Behavior changes by stuffing demonstrations into the prompt. It is easy to deploy, but long prompts hit context, cost, and dilution limits.
Update weights or adapters
Behavior is stored in model parameters or low-rank updates. The ecosystem is mature, but the adaptation travels through input-dependent representations.
Optimize layer-wise KV prefixes
Demonstrations are compressed into persistent key-value prefixes. The model consults them like learned memory without changing the backbone.
ReasonCACHE is one learned-prefix-cache instance.
This page stays focused on the ReasonCACHE paper and our vLLM support. The shared Cartridges plus ReasonCACHE taxonomy now lives on the Learned Prefix Caches page.
Shared mechanism
Cartridges, ReasonCACHE, document caches, and skill caches all attach learned layer-wise K/V prefixes to a frozen model. The runtime object is a learned prefix cache.
ReasonCACHE gap
ReasonCACHE validates learned KV prefixes for reasoning when curated traces already exist. KNLP is testing Active Reading Cache Induction as the missing step for raw skills, documents, and procedural sources that do not already contain traces.
vLLM accepts learned prefixes; PI gives the first skill signal.
The vLLM branch loads learned KV prefixes through the cartridge connector path and emits Pareto reports from scored result JSONs. The H100 skill-trace run, H100 PI stabilization run, H100 public-strata scale run, GSM8K ReasonCACHE sanity check, A100 SCI/Active Reading retest, A100 skill-cache convergence curve, and LongHealth document retests add quality evidence for the induction layer, not just the connector.
Result components
| Area | Status |
|---|---|
| ReasonCacheConnector | Alias registered for the cartridge connector path. |
| Learned KV prefixes | Checkpoint resource kind accepts ReasonCACHE / KV-prefix payloads. |
| Placeholder tokens | Required until vLLM grows true virtual-prefix scheduling. |
| SkillsBench harness | Run, compare, and normalize arm results. |
| Pareto frontier | Emit per-task and aggregate-by-arm JSON/CSV reports. |
| PI ablations | Compare raw skill NTP, fixed self-study, proper AR-TA, AR-TS, R-PI, and BO-PI. |
| PI scale | Public-strata scale run failed quality transfer across all non-empty verifier tasks. |
| Curated traces | GSM8K sanity confirms ReasonCACHE helps when reasoning traces already exist. |
Branch stack
| Branch / commit | Patch |
|---|---|
| 20260629-learned-prefix-cache | Non-routing branch based on the cartridge upstream work. |
| 0ac3a390d | Add learned prefix cache support for Cartridges, ReasonCACHE, and generic KV prefixes. |
| 20260430-cartridges-upstream | Cartridge connector base used as the serving foundation. |
Name the skill files and the induction target.
These are the same SkillsBench tasks and SKILL.md files from the cartridge experiments. The learned-prefix arms remove SKILL.md text from the online prompt and supply behavior through injected KV state. The new question is which induction method produces useful training traces. The full ARCI bridge analysis is on the Learned Prefix Caches page.
Skill files and prompt bodies under test
Character counts come from the harness that loads environment/skills/**/SKILL.md. The ReasonCACHE prompt body is the same text as the no-skill arm; placeholder tokens are added separately after tokenization.
| Task | Individual SKILL.md files | Loaded skill chars | Full-skill prompt chars | ReasonCACHE prompt chars | Data files |
|---|---|---|---|---|---|
| Excel table into PPT |
pptx: 25,534 chars / 25,552 B xlsx: 5,243 chars / 5,247 B |
30,812 | 31,683 | 850 | 0 |
| Powerlifting coefficient calculation |
powerlifting: 14,857 chars / 14,910 B senior-data-scientist: 5,630 chars / 5,630 B xlsx: 5,243 chars / 5,247 B |
25,808 | 31,050 | 5,221 | 1 |
| Recover missing XLSX data |
data-reconciliation: 2,482 chars / 2,492 B xlsx: 5,243 chars / 5,247 B |
7,775 | 10,152 | 2,356 | 2 |
| Weighted GDP calculation | xlsx: 5,243 chars / 5,247 B | 5,260 | 6,497 | 1,216 | 0 |
Cartridge-era SkillsBench baseline, not ReasonCACHE
These pass rates came from the older cartridge experiments on the same skill files. They are useful baselines, but they do not answer whether ReasonCACHE is better on these skills.
| Task | Full skill | Truncated skill | No skill | Cartridge 50% |
|---|---|---|---|---|
| Excel table into PPT | 0 / 8 | 7 / 8 | 7 / 8 | 7 / 8 |
| Powerlifting coefficient calculation | 9 / 11 | 5 / 11 | 5 / 11 | 5 / 11 |
| Recover missing XLSX data | 0 / 1 | 2 / 19 | 1 / 19 | 14 / 19 |
| Weighted GDP calculation | 1 / 27 | 1 / 27 | 1 / 27 | 1 / 27 |
H100 ReasonCACHE trace ablation
The completed pilot ran ten arms per task. The useful comparison is not "ReasonCACHE versus Cartridges" yet; it is raw skill text versus generated behavior traces for the same learned-prefix mechanism.
| Task | Raw skill NTP | Fixed self-study KL | ARCI skill KL | ARCI reasoning KL |
|---|---|---|---|---|
| Excel table into PPT | 0 / 8 | 0 / 8 | 7 / 8 | 7 / 8 |
| Powerlifting coefficient calculation | 0 / 11 | 0 / 11 | 0 / 11 | 0 / 11 |
| Recover missing XLSX data | 1 / 19 | 12 / 19 | 1 / 19 | 14 / 19 |
| Weighted GDP calculation | 10 / 27 | 10 / 27 | 10 / 27 | 10 / 27 |
H100 PI stabilization on XLSX recovery
The stabilization run focused on the clearest skill-cache signal: recovering missing spreadsheet data. It tests whether stronger induction prompts improve the same learned-prefix mechanism.
| Family | Accuracy | Request tokens | Prefix tokens | Main read |
|---|---|---|---|---|
| BO-PI | 17 / 19 | 4,072 | 1,744 | Best score, but seed-sensitive. |
| CSB-PI | 14 / 19 | 3,641 | 1,744 | More stable focused candidate. |
| SS-PI | 12 / 19 | 3,505 | 1,744 | Cartridges-style self-study baseline. |
| No skill | 8 / 19 | 1,732 | 0 | Lower cost, lower quality. |
H100 PI scale across public skill strata
The next run widened the task surface instead of chasing the XLSX win. It used the same four public strata chosen for the bridge: small, deterministic-random, medium, and large SkillsBench tasks. All non-empty verifier tasks scored zero across every PI family.
| Family | Aggregate | Rows | Main read |
|---|---|---|---|
| No skill / full skill | 0 / 16 each | 8 | Prompt baselines did not solve the selected tasks. |
| SS-PI, AR-TA, AR-TS, R-PI | 0 / 16 each | 16 | No single-seed PI arm transferred. |
| CSB-PI | 0 / 48 | 12 | Three seeds did not reproduce the focused XLSX gain. |
| BO-PI | 0 / 48 | 12 | The high-score XLSX arm did not generalize. |
GSM8K ReasonCACHE sanity check
This checks the paper's easier case: reasoning traces already exist. It does not solve prefix induction for raw skills, but it confirms the learned-prefix mechanism is useful when trained on curated traces.
| Family | Accuracy | Mean request tokens | Prefix tokens | Main read |
|---|---|---|---|---|
| ReasonCACHE NTP | 20 / 24 | 251.6 | 512 | Best sanity row. |
| ReasonCACHE NTP | 19 / 24 | 239.9 | 256 | Lower prefix cost, same score as prefill. |
| Text prefill | 19 / 24 | 277.9 | 256 | Strong initialization control. |
| No cache | 17 / 24 | 301.7 | 0 | Mechanism baseline. |
A100 SCI and Active Reading retest
The retest fixed two labels at once: paper SCI is sampled contiguous chunks, not the legacy strided-RoPE initializer; and paper Active Reading has task-agnostic and task-specific prompt families. The best result came from proper task-agnostic Active Reading, not from raw skill continuation.
| Task | Best A100 row | No skill | Main read |
|---|---|---|---|
| Excel table into PPT | 0 / 8 | 0 / 8 | No tested shallow arm helped in this matrix. |
| Recover missing XLSX data | AR-TA + strided-RoPE: 15 / 19 | 6 / 19 | Task-agnostic Active Reading became the best PI arm. |
| syzkaller ppdev syzlang | best learned-prefix rows: 1 / 7 | 0 / 7 | Weak signal, but first-k stayed below SCI and strided-RoPE. |
A100 convergence curve
The follow-up run saved and scored xlsx checkpoints at optimizer steps 0, 1, 2, 4, 8, 16, 24, and 48. This tests steps-to-quality directly, instead of treating final wall-clock as convergence. It is a skill-cache curve, not document-side Cartridges evidence.
| PI | Initializer | Fastest useful step | Best | Main read |
|---|---|---|---|---|
| AR-TA | first-k | 8 to reach 17 / 19 | 17 / 19 | Best quality row. |
| AR-TA | strided-RoPE | 4 to reach 16 / 19 | 16 / 19 | Fastest high-quality row. |
| AR-TA | best SCI seed | 16 to reach 13 / 19 | 13 / 19 | No SCI convergence win for AR-TA. |
| SS-PI | SCI seed 2 | 4 to reach 14 / 19 | 14 / 19 | SCI can work when sampled chunks are useful. |
| SS-PI | first-k | 2 to reach 12 / 19 | 12 / 19 | Fast early baseline. |
ReasonCACHE prefix sizing contract
- inferred Prefix length is read from the checkpoint num_tokens.
- aligned vLLM aligns learned-prefix length to the cache block size.
- explicit Placeholder tokens remain required until native virtual prefixes exist.
| Item | Validated value |
|---|---|
| Checkpoint resource kinds | reasoncache and kv_prefix |
| Placeholder token id | 0 by default; configurable in request and connector config |
| Unit request plan | 32 placeholders + 3 task prompt tokens = 35 online prompt tokens |
| Checkpoint inference test | 34 raw prefix tokens align to 32 at block size 16 |
| Connector fixture | 2 layers, 2 KV heads, 32 prefix tokens, head dimension 4 |
| Old xlsx cartridge reference | 2,702 original skill tokens -> 1,351 budget tokens; 64 layers; 354,193,931 B artifact |
| H100 pilot learned-prefix checkpoints | 672 to 3,856 prefix tokens; 36.8 to 210.9 MiB artifacts across the four tasks. |
Pareto now compares induction arms, not just prompt size.
The analyzer maximizes pass rate while keeping request tokens, virtual prefix tokens, prefix bytes, offline induction time, and reuse count separate. The current frontier combines controlled bridge strata, H100 PI stabilization, H100 public-strata scale, and the GSM8K curated-trace sanity check. It is still a pilot, not a final claim.
Original H100 pilot aggregate
Aggregate pass rate across the four old SkillsBench tasks. All learned-prefix arms still include placeholder tokens under the current vLLM contract.
Current frontier axes
| Axis | Why it stays separate |
|---|---|
| Request tokens | Online prompt plus generated tokens drive serving cost. |
| Prefix bytes | Loaded learned prefixes consume cache residency. |
| Offline seconds | Induction and training cost only amortize with reuse. |
| Reuse count | A prefix shared across many requests changes the frontier. |
PEFT lineage as context, not the main event.
This material comes from the PEFT evolution starting point, but the ordering is inverted for a ReasonCACHE page. Read this after the results and implementation status.
Prefix tuning is the ancestor that matters most here.
Prefix tuning learns continuous key-value prefixes at each transformer layer while keeping the backbone frozen. ReasonCACHE specializes that mechanism for reasoning: demonstrations become optimized layer-wise cache state instead of long prompt tokens.
Prompt tuning is shallower.
Prompt tuning learns input embeddings and lets the frozen model project them through the stack. ReasonCACHE directly edits the attention-side interface by learning key-value prefixes at every layer.
LoRA remains the deployment default, but has a different bottleneck.
LoRA stores adaptation as low-rank weight deltas. The ReasonCACHE paper argues that low-rank updates are tied to input rank, while prefix tuning injects additional key-value directions directly into attention.
Cartridges made trained KV state feel deployable.
Cartridges target knowledge retrieval and synthesis from compressed document state. ReasonCACHE targets skill acquisition and reasoning. Both are learned prefix caches; their main difference is the source data and induction method used before training.
Active Reading Cache Induction is the bridge under test.
ARCI names the step that generates trainable behavior from raw source material. It lets the same learned-prefix-cache mechanism serve document, skill, and reasoning workloads when curated traces are not already available.
Prefix tuning
Layer-wise learned prefixes for frozen transformers.
LoRA
Low-rank weight adaptation becomes the practical default.
Active Reading
Generate document-specific study strategies and training views.
Cartridges
Train a KV cache as a reusable document representation.
ReasonCACHE
Train a KV cache as a reusable reasoning interface.