Temporal Versioning: Git for Your Cache

Your cache has amnesia. Every SET overwrites the previous value. It is gone — irretrievably, immediately, permanently. When the 3 AM PagerDuty fires and the post-mortem asks “what did the cache serve when the bug happened?” the answer is: nobody knows. The value was overwritten before anyone thought to look. We built the fix. It is called temporal versioning, and the analogy is exact: Git for your cache.

Production Debugging Needs Version History

Forty percent of production incidents involve stale or incorrect cached data. That number comes from internal surveys across teams running multi-service architectures, and it is consistent with what we hear from every enterprise prospect. The cache served wrong data. Users saw it. The incident is over, the bug is fixed, and now the post-mortem begins.

The first question in every post-mortem is: what happened? For database issues, you have transaction logs and point-in-time recovery. For application errors, you have structured logging and distributed traces. For cache issues, you have nothing. The cache overwrites history on every write. By the time anyone investigates, the evidence is gone.

This is the debugging gap. The cache is the fastest-changing data store in your stack — values updated thousands of times per second — and it is the only one with zero historical record. Temporal versioning closes that gap.

# What did the cache serve during the 3 AM incident?
GET pricing:enterprise AT 2026-03-27T03:00:00
# Returns: {"monthly": 0, "annual": 0}  -- the bug: pricing was zeroed

# When did the bad value first appear?
HISTORY pricing:enterprise LIMIT 5
# v4  03:14:00  SET  api-server-3  {"monthly": 299, "annual": 2990}  -- fix deployed
# v3  02:47:00  SET  api-server-1  {"monthly": 0, "annual": 0}       -- corruption
# v2  02:46:59  SET  api-server-1  {"monthly": 299, "annual": 2990}  -- still good
# v1  00:00:00  SET  api-server-2  {"monthly": 299, "annual": 2990}  -- midnight refresh

# Root cause: api-server-1 wrote a zeroed value at 02:47:00

That is the entire investigation. Three commands. The version history shows exactly when the bad value was written, which server wrote it, and what the previous good value was. Without temporal versioning, this investigation takes hours of log correlation, guess-and-check, and “I think it was probably around 3 AM.”

The Compliance Angle: SOC 2, FINRA, HIPAA

Compliance auditors ask a specific class of questions that caches cannot currently answer: “Can you prove what data was served to users at time X?”

For SOC 2 Type II, auditors want evidence that access controls and data handling were correct during the audit period. For FINRA, the question is whether trade-related data was accurate at the time of execution. For HIPAA, it is whether patient data was correctly served to authorized users at specific timestamps.

Today, the answer to all of these is a painful combination of log mining, database snapshots, and hand-waving. The cache — which is often the system that actually served the data to the end user — has no record. It is the gap in the audit trail.

This transforms the cache from an audit liability into an audit asset. Instead of “we cannot prove what the cache served,” the answer becomes “here is the exact value, with a cryptographic timestamp, queryable at any point in the retention window.”

A/B Testing Cache Behavior

You deployed a new caching strategy at 2 PM. Hit rates changed. Latency shifted. Was the cache serving different data before and after? Was the new strategy caching stale values that the old one correctly invalidated? Without version history, you are comparing metrics (hit rate, latency) without the ability to inspect the actual cached values.

The DIFF command solves this directly:

# What changed in the cache across the deploy window?
DIFF product:catalog 2026-03-27T13:00:00 2026-03-27T15:00:00
# 3 versions changed
# 13:45 -> 14:02: price field updated (expected, DB write)
# 14:05 -> 14:12: description truncated (unexpected -- new strategy bug)
# 14:12 -> 14:30: description restored (hotfix)

Now you can see exactly how cache values evolved across a time window. Before/after deploy comparisons become precise instead of statistical. You are not guessing from hit-rate curves — you are reading the actual data.

GET AT: The Time-Travel Query

The core primitive is simple. Every SET appends a new version to the key’s version chain instead of overwriting. Each version stores the value, the timestamp, the writer ID (which server or service performed the write), and the operation type (SET, DEL, CDC update). The version chain is an append-only log, indexed by timestamp.

GET key AT timestamp performs a binary search on the version chain and returns the version that was active at the requested time. Latency: approximately 0.5 microseconds. A standard GET (without the AT clause) returns the current value with zero additional overhead — the version chain is never consulted on the hot read path.

HISTORY key returns the full version timeline. DIFF key t1 t2 shows what changed between two timestamps. VERSIONS key returns the count of retained versions.

Retention Policies and Memory Management

Version history consumes storage. The question is how much and for how long. Cachee makes this configurable per key prefix:

• Hot operational data (session:*): 1–24 hour retention. Versions are garbage-collected quickly.
• Application state (user:*): 7-day retention. Enough for post-mortem debugging across a full incident lifecycle.
• Compliance data (audit:*): 30–90 day retention. Satisfies SOC 2 audit windows.
• Audit-critical (txn:*): Indefinite retention, archived to cold storage.

The storage math is straightforward: 10M keys × 24 versions/day × 1KB average value = 240GB/day. This composes naturally with hybrid tiering: current versions live in RAM for sub-microsecond access, recent versions tier to NVMe, and compliance-retention versions archive to cold storage. The garbage collector runs on a background thread, respects retention policies, and never blocks the hot path.

Composition: Temporal + Self-Healing + Contracts

Temporal versioning multiplies the value of other Cachee primitives.

Temporal + Self-Healing: Self-healing detects anomalous cache values and corrects them. Temporal versioning shows when the anomaly started. Together: detect the poisoned value, trace the version chain back to the exact write that introduced it, and automatically revert to the last known-good version. Full forensic trail, zero manual intervention.

Temporal + Cache Contracts: Contracts enforce value invariants at write time (e.g., “price must be positive”). Temporal versioning proves contract compliance at any historical point. An auditor queries a key at a past timestamp and verifies it against the contract. Compliance proof becomes a single API call.

Temporal + Hybrid Tiering: Version data tiers naturally. Current versions in RAM. Recent in NVMe. Compliance-retention in cold archive. The tiering engine manages promotion and demotion automatically, so version history scales without manual capacity management.

Related Reading

• Temporal Versioning Product Page
• Temporal Versioning Technical Specification
• Self-Healing Cache
• Cache Contracts
• Hybrid Tiering

Observability And What To Measure

You can't tune what you can't measure. The four metrics that matter for any production cache deployment, in order of importance:

• Hit rate, broken down by key prefix or namespace. A global hit rate of 92% sounds great until you discover that one critical namespace is sitting at 40% and dragging your tail latency. Per-prefix hit rates expose which workloads are getting cache value and which aren't.
• Latency percentiles, not averages. p50, p95, p99, and p99.9 for both cache hits and cache misses. The cache miss latency is your fallback path performance — when the cache fails, this is what your users actually experience.
• Memory pressure and eviction rate. If your eviction rate is climbing while your hit rate stays flat, you're under-provisioned. If both are climbing, your access pattern shifted and you need to retune TTLs or rethink what you're caching.
• Stale-read rate. The percentage of cache hits that returned a value the application then discovered was stale. This is the canary for your invalidation strategy. If it's above 1%, your invalidation logic has a bug.

Cachee exposes all four out of the box via Prometheus metrics on the standard scrape endpoint, plus a real-time SSE stream for dashboards that need sub-second visibility. The right time to wire these into your monitoring stack is before the migration, not after the first incident.

Three Pitfalls That Burn Teams

Three things consistently bite teams during the first month of running an in-process cache alongside or instead of a network cache. We've seen each of these in production. Here's how to avoid them.

• Hot working set sizing. The L0 hot tier is fast because it lives in your application process. If your hot working set is 50 GB and your heap budget is 8 GB, you can't put all of it in L0. Measure your actual hot key distribution before deciding what fits in-process versus what needs an L1 sidecar or an L2 fallback. The Cachee admission filter will protect you from polluting the cache, but it can't conjure RAM that doesn't exist.
• TTL semantics drift. Redis processes TTL expirations lazily on access plus a background sweeper. Cachee processes them in the same lock-free read path via monotonic timestamp comparison. Behavior is identical for the vast majority of workloads, but if you depend on Redis-specific behaviors like OBJECT IDLETIME tracking or precise keyspace expiration notifications, validate the semantics for your specific use case before flipping production traffic over.
• Eviction policy assumptions. Redis defaults to allkeys-lru. Cachee uses CacheeLFU which makes different admission decisions on workloads with skewed access frequency distributions. Most teams see hit rate improvements after migration, but if you've spent years tuning your application around LRU behavior — choosing TTLs based on how LRU evicts cold data — expect a brief transition period where you re-tune TTLs and access patterns to match the new admission policy.

Average Latency Hides The Real Story

Average latency is the most misleading number in cache benchmarking. The percentile distribution is what actually breaks production systems. Tail latency — the slowest 0.1% of requests — is where users notice the lag and where SLAs get violated.

Percentile	Network Redis (same-AZ)	In-process L0
p50	~85 microseconds	28.9 nanoseconds
p95	~140 microseconds	~45 nanoseconds
p99	~280 microseconds	~80 nanoseconds
p99.9	~1.2 milliseconds	~150 nanoseconds

The p99.9 spike on networked Redis isn't a bug — it's the cost of running a single-threaded event loop that occasionally blocks on background tasks like RDB snapshots, AOF rewrites, and expired-key sweeps. Cachee's L0 stays inside a few hundred nanoseconds because the hot-path read is a lock-free shard lookup with no background work scheduled on the same thread.

If your application is sensitive to tail latency — payments, real-time bidding, fraud detection, trading — the p99.9 number is the one to optimize against. Average latency improvements that don't move the tail are vanity metrics.

When Caching Actually Helps

Caching isn't free. It introduces a consistency problem you didn't have before. Before adding any cache layer, the question to answer is whether your workload actually benefits from caching at all.

Caching helps when three conditions hold simultaneously. First, your reads dramatically outnumber your writes — typically a 10:1 ratio or higher. Second, the same keys get read repeatedly within a window where a cached value remains valid. Third, the cost of computing or fetching the underlying value is meaningfully higher than the cost of a cache lookup. Database queries that hit secondary indexes, RPC calls to slow upstream services, expensive computed aggregations, and rendered template fragments all qualify.

Caching hurts when those conditions don't hold. Write-heavy workloads suffer because every write invalidates a cache entry, multiplying your work. Workloads with poor key locality suffer because the cache wastes memory storing entries that never get reused. Workloads where the underlying fetch is already fast — well-indexed primary key lookups against a properly tuned database, for example — gain almost nothing from caching and inherit the consistency complexity for no reason.

The honest first step before any cache deployment is measuring your actual read/write ratio, key access distribution, and underlying fetch latency. If your read/write ratio is below 5:1 or your underlying database is already returning results in single-digit milliseconds, the engineering time is better spent elsewhere.