kmemo-core/dev.kmemo/CacheStats

CacheStats

data class CacheStats(val lookups: Long, val hits: Long, val misses: Long, val belowThreshold: Long, val guardRejections: Long, val verifierRejections: Long, val writes: Long, val guardRejectionsByGuard: Map<String, Long> = emptyMap(), val degradedLookups: Long = 0, val writesVetoed: Long = 0, val exactHits: Long = 0, val embedderMismatches: Long = 0, val savings: Map<String, Savings> = emptyMap(), val writesNotAdmitted: Long = 0)

Counters for one SemanticCache instance, from creation to now.

The breakdown of misses is the part worth watching. A high belowThreshold means your traffic repeats less than you assumed, or your threshold is too tight for your embedding model. A high guardRejections means the opposite: prompts are landing close together and the guards are catching near-misses your threshold alone would have served.

Constructors

CacheStats

constructor(lookups: Long, hits: Long, misses: Long, belowThreshold: Long, guardRejections: Long, verifierRejections: Long, writes: Long, guardRejectionsByGuard: Map<String, Long> = emptyMap(), degradedLookups: Long = 0, writesVetoed: Long = 0, exactHits: Long = 0, embedderMismatches: Long = 0, savings: Map<String, Savings> = emptyMap(), writesNotAdmitted: Long = 0)

Properties

belowThreshold

val belowThreshold: Long

Misses where the best candidate scored below the threshold.

degradedLookups

val degradedLookups: Long

Calls that ran uncached because the Embedder threw and EmbedFailurePolicy.FALL_BACK_TO_COMPUTE stepped aside.

embedderMismatches

val embedderMismatches: Long

Lookups that met a candidate above the threshold written by a different Embedder.identity.

exactHits

val exactHits: Long

Hits served by the exact-match layer, without embedding the prompt or searching the store.

guardRejectionRate

val guardRejectionRate: Double

Fraction of lookups that reached a guard and were stopped there, in [0.0, 1.0].

guardRejections

val guardRejections: Long

Misses where a guard vetoed a candidate that had cleared the threshold.

guardRejectionsByGuard

val guardRejectionsByGuard: Map<String, Long>

guardRejections broken down by the dev.kmemo.guard.MatchGuard.name that fired.

hitRate

val hitRate: Double

Fraction of lookups served from cache, in [0.0, 1.0]. 0.0 when nothing has been looked up.

hits

val hits: Long

Lookups that served a cached response.

lookups

val lookups: Long

Total SemanticCache.lookup and SemanticCache.getOrPut calls.

misses

val misses: Long

Lookups that did not. Always lookups - hits.

savings

val savings: Map<String, Savings>

What the hits in each scope did not cost, for every scope the caller declared TokenPrices for.

verifierRejections

val verifierRejections: Long

Misses where the verifier vetoed a candidate that had cleared threshold and guards.

writes

val writes: Long

Entries written through SemanticCache.put or SemanticCache.getOrPut.

writesNotAdmitted

val writesNotAdmitted: Long

Writes an AdmissionPolicy held back because the prompt had not been asked often enough yet.

writesVetoed

val writesVetoed: Long

Writes a CachePolicy refused.