ZREVRANGE read-side consumer, atomic top-50 trim on write, hydrate-time stale-ID filtering — distinct from semantic search.
Milestone 3.D.3 — Hot Cache (Redis Sorted Set)
Status: Complete
Goal: Track D — Read/Ranking Pipeline
Phase: 3 — Core Memory Substrate
Estimated effort: 2 days
Why This Milestone Exists
The hot cache provides fast access to an agent's top memories by write-time composite score. Before 3.D.3 the write path ZADDed to {org_id}:hot_memories:{agent_id} but never trimmed (unbounded past 50) and nothing read the sorted set. This milestone adds atomic top-50 trim on write and the first read consumer for Phase 3.5 parallel retrieval.
Design correction: Hot cache is not wired into find_similar() — semantic search and hot memories are parallel, separately-budgeted inputs per ARCHITECTURE.md. See ADR-0059.
Non-Goals
- Changing the hot cache capacity (top-50, as originally specified)
- Replacing the hot cache with a different caching strategy
- Full composite scoring in the cache layer (write-time
relevance=1.0is intentional) - HTTP endpoint (deferred to Phase 3.5 context assembly consumer)
- Hijacking
POST /v1/memories/searchwith cache-first semantics
Delivered
| Component | Path |
|---|---|
| Shared keys + score | app/cache/hot_keys.py, app/cache/hot_score.py |
| Atomic write trim | app/cache/hot_write.py (Lua ZADD + ZREMRANGEBYRANK + EXPIRE) |
| Read consumer | app/read/hot_cache.py — MemoryHotCacheReader.get_hot_memories() |
| Metrics | ibex_memory_hot_cache_read_total{result} |
Redis key pattern: {org_id}:hot_memories:{agent_id} — namespaced per established convention.
Invalidation: hydrate-time filter for deleted/superseded rows; explicit ZREM deferred to delete/GDPR paths (Track E).
Success signals
- Hot cache score formula reuses
CATEGORY_HALF_LIFE_DAYSviacompute_hot_cache_score()/composite_score() - Top-50 trim (
ZREMRANGEBYRANK) and TTL refresh verified by test (atomic Lua per write) - Redis keys are
org_id-namespaced; cross-tenant isolation tested - Distinct read path —
find_similar()unchanged - Repo guards / CI checks pass
Prerequisites
- Milestone 3.D.2 (composite scoring v2)
Last updated on