ADR-0059: Hot cache read pathCopy Anchor Link

• Status: Accepted
• Date: 2026-08-29
• Authors: IBEX Harness team
• Milestone: 3.D.3 Hot cache (Redis sorted set)

ContextCopy Anchor Link

Milestone 3.C.5 / ADR-0057 writes per-agent hot sorted sets ({org_id}:hot_memories:{agent_id}) on memory create using composite_score() with relevance=1.0 (no query at write time). Before 3.D.3:

1. No trim — ZSETs grew unbounded past the spec'd top-50 capacity.
2. No read consumer — hot cache was write-only; context assembly's parallel retrieval design (ARCHITECTURE.md) expects a distinct hot-memory source separate from semantic search.

Options ConsideredCopy Anchor Link

1) Blend hot cache into find_similar() as cache-first semantic searchCopy Anchor Link

Pros: Single read API for callers.

Cons: Hot ZSET scores lack query relevance (relevance=1.0 at write time). Serving cache hits as semantic search results would return frequently-accessed but query-irrelevant memories — violates POST /v1/memories/search contract. Conflicts with Phase 3.5 parallel retrieval (hot + cold are separately budgeted inputs).

2) Distinct MemoryHotCacheReader.get_hot_memories() (chosen)Copy Anchor Link

Pros: Matches context assembly architecture; preserves semantic search contract; service-layer API ready for Phase 3.5.C.2 and Track E ISO-* tests without proxy changes (Phase 3 exit #10).

Cons: No HTTP surface in 3.D.3 (deferred like VectorStore before 3.D.1).

DecisionCopy Anchor Link

1. Read API: MemoryHotCacheReader.get_hot_memories(HotMemoryQuery) — ZREVRANGE + Postgres hydrate with org_id + agent_id defense-in-depth filters. find_similar() unchanged.
2. HTTP: Deferred — internal service API only until Phase 3.5 context assembly consumes it.
3. Write trim: Atomic Lua script — ZADD, ZREMRANGEBYRANK 0 -51, EXPIRE — keeps top 50 by score per write (app/cache/hot_write.py).
4. Scoring: Reuse compute_hot_cache_score() → shared composite_score() / CATEGORY_HALF_LIFE_DAYS (ADR-0057).
5. Stale members: Hydrate-time filtering (status='active', deleted_at IS NULL) — stale ZSET members dropped on read. Explicit ZREM on delete/supersede deferred until unified write-path invalidation (Track E GDPR cascade).
6. Metrics: ibex_memory_hot_cache_read_total{result="hit|empty|error"}.
7. Result shape: MemorySearchResult with source="hot_cache"; similarity = write-time ZSET composite score (not query relevance).

ConsequencesCopy Anchor Link

• Phase 3.5.C.2 parallel retriever wires get_hot_memories alongside cold semantic search.
• Track E 3.E.1 ISO-* matrix can assert Redis key + hydrate isolation without new HTTP routes.
• Hot cache capacity remains fixed at 50; changing the capacity is out of scope.

RelatedCopy Anchor Link

• ADR-0057 — write-path ZADD
• ADR-0058 — semantic search (orthogonal)
• 3.5.C.2 Parallel retrieval — consumer milestone