session-cache-analysis

Analyze prompt cache hit rates of Synapse sessions from checkpoint usage metadata.

7|2|Updated Jul 21, 2026
One-click install
npx skills add https://github.com/alex8224/synapse-agent --skill session-cache-analysis-alex8224
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: session-cache-analysis
Source: https://github.com/alex8224/synapse-agent/tree/main/skills/session-cache-analysis
Command: npx skills add https://github.com/alex8224/synapse-agent --skill session-cache-analysis-alex8224

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a Synapse coding-agent session shows unexpectedly high token costs or low prompt cache hit rates, it is hard to tell whether the misses are normal incremental misses or an abnormal full cache eviction, and even harder to find the root cause of an eviction. ## Core Features & Use Cases - Overall and per-turn hit-rate computation: Aggregates cache_read and input_tokens from checkpoint SQLite messages to compute overall, per-turn, and per-call cache hit rates. - Miss classification: Distinguishes normal incremental misses (large new tool results) from full cache eviction by tracking the absolute cache_read value rather than the percentage. - Eviction root-cause diagnosis: Compares wire fingerprints in model_request_compression_events to identify whether system prompt changes, tool set changes, summarization, truncation, or upstream provider eviction caused the cache bust. - Use Case: A user notices one turn of a session suddenly billed tens of thousands of uncached input tokens; this Skill locates the exact call, confirms it was a full eviction, and shows the tool schema set changed between calls. ## Quick Start Analyze the prompt cache hit rate of my Synapse session and tell me why the hit rate collapsed on turn 12.

Frequently Asked Questions about session-cache-analysis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check the prompt cache hit rate of a Synapse session?

Load all messages for the thread from .synapse/checkpoints.sqlite using load_messages_from_sqlite_file, then aggregate usage with aggregate_usage_from_messages. The hit rate is cache_tokens divided by input_tokens; do not use transcript.sqlite, which only stores the last turn.

How to tell if a cache miss is normal or a full cache eviction?

Look at the absolute cache_read value, not the percentage. Incremental misses keep cache_read rising while input_tokens grow from new tool results; a full eviction shows cache_read dropping sharply while input_tokens stays nearly flat.

Why did my prompt cache hit rate suddenly drop in one turn?

Compare the failing call with the previous one in the model_request_compression_events table. Changes in system_hash, tool_count, added or removed tools, summarization_saved_tokens, or prompt_saved_tokens each indicate a different root cause; if nothing changed, the eviction happened upstream at the provider.

Does a large tool result invalidate the prompt cache?

No. A large tool result only makes the new content bill as a miss while the old prefix still hits cache, and the next call recovers to high hit rates. Only a drop in the absolute cache_read value indicates real eviction.

What are the limitations of transcript.sqlite for usage analysis?

The transcript_usage table uses INSERT OR REPLACE and keeps only the last turn's per-turn usage, with last_cache_tokens always zero. It cannot be used for session-level cumulative hit rates; always aggregate from checkpoint messages instead.