Chapter 39: Prompt Cache Stability

Cacheability is a serialization contract. Semantic similarity is not enough.

Public-source snapshot: implementation details are examples from public Kocoro origin/main at commit 4ec6772, reviewed 2026-07-27. Treat the invariant as the lesson and re-check constants against current source.

39.1 The problem

Prompt caching is defeated by harmless reordering, per-turn schema filtering, timestamps, and in-place history rewrites. The visible content may be semantically equivalent while its bytes no longer share a provider cache prefix.

39.2 The design rule

Build a canonical prefix: stable system scaffold, deterministically ordered tools, and stable Skill metadata. Enforce allowed-tools at execution time instead of removing schemas per turn. When creating forked requests, clone mutable slices and preserve byte equality for the shared prefix; instrument every rewrite that intentionally breaks it.

39.3 Snapshot evidence

Source snapshot	Observation
`4ec6772`	`BuildForkedRequest` preserves a byte-equal shared prefix
`4ec6772`	`allowed-tools` is an execution restriction, not schema filtering
`4ec6772`	in-place message rewrites emit cache-compaction telemetry

The values above describe one dated implementation, not a universal contract.

39.4 Implementation checklist

Snapshot serialized prefixes in tests.
Sort every map-derived list before rendering.
Track cache hit rate beside task success and latency.

39.5 Takeaway

Cacheability is a serialization contract. Semantic similarity is not enough.

Read these chapters as one system: context, tool schemas, persistence, steering, time discipline, loop detection, and concurrency affect one another.

@incollection{zhang2026aiagent_en_chapter-39-prompt-cache-stability, author = {Zhang, Wayland}, title = {Chapter 39: Prompt Cache Stability}, booktitle = {AI Agent Architecture: From Single Agent to Enterprise Multi-Agent Systems}, year = {2026}, url = {https://waylandz.com/ai-agent-book-en/chapter-39-prompt-cache-stability/} }