Skip to content

server: a disk tier for the prompt cache (--cache-disk) - #78

Open
joelteply wants to merge 1 commit into
164bbff9/server-a-saved-page-keeps-checkpoints-jufrom
fable/prompt-cache-disk-tier
Open

joelteply wants to merge 1 commit into
164bbff9/server-a-saved-page-keeps-checkpoints-jufrom
fable/prompt-cache-disk-tier

Conversation

@joelteply

Copy link
Copy Markdown

Spills prompt-cache entries evicted from --cache-ram to a directory and reads them back on a match. See the commit message for the M5 measurements (2026-10-27). Pairs with continuum card f35cbd9d.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LoTjvf5j3Ez13g6k8mRkFo

…isk-mib N)

An entry evicted from --cache-ram was dropped, so a mind whose saved conversation
aged out re-prefilled it whole. With --cache-disk the oldest resident entry is
written to DIR instead (its sequence state and its checkpoints' data); its tokens
and checkpoint positions stay in RAM so a lookup still matches it, and a match
reads it back and removes the file. An entry larger than the whole RAM tier goes
straight to disk instead of displacing every other entry; the disk tier evicts its
own oldest at its limit. States another engine instance left in DIR are removed at
start; this instance's files are removed when the cache is destroyed.

Why: on the M5 (2026-10-27) the RAM tier was 11,961 MiB holding 2.4-6.6 GiB
entries; macOS compressed 13-15 GB of the engine and swapped 11.9 of 13.3 GB, so
the cache the engine believed resident was paying decompression and swap reads,
and 40+ entries were dropped ("removing oldest entry"), one 3,845 MiB state
skipped outright. A small RAM tier that stays uncompressed plus a disk tier
read at SSD speed keeps every resident's conversation restorable.

Logs: "spilled prompt cache entry to disk: N tokens, X MiB in T ms" and
"restored prompt cache entry from disk: ...", the receipts for the live read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LoTjvf5j3Ez13g6k8mRkFo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant