ZADD/ZREVRANGE sorted set per agent, top-50 capacity, TTL-based eviction for cold agents — using category-conditional recency from 3.D.2 for consistency.
Milestone 3.D.3 — Hot Cache (Redis Sorted Set)
Status: Planned
Goal: Track D — Read/Ranking Pipeline
Phase: 3 — Core Memory Substrate
Estimated effort: 2 days
Why This Milestone Exists
The hot cache provides sub-millisecond access to an agent's most frequently relevant memories, avoiding a full pgvector search on every request. The design uses a Redis sorted set per agent with a simplified scoring formula that must stay consistent with the full composite scorer's recency model.
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 (simplified formula is intentional)
Orientation (indicative)
Named paths, package layouts, libraries, schemas, env vars, and commands anywhere on this page are rough sketches for orientation — inspiration and a baseline, not a required change list.
During implementation, expect to:
- open the live tree and follow existing patterns before inventing new ones
- research current constraints (latency, tenancy, deploy shape, libraries) more deeply than this page can
- advance the design beyond the sketch where measurement or code reality says so
- land work in different filenames, merged packages, deferred docs, or new surfaces when the situation calls for it
Prefer outcomes over matching any particular file tree or command sequence.
Areas that may be involved (situational — not a checklist):
- Memory service / repositories
- Vector store / search
- Caching / Redis
Suggested naming (provisional)
Rename freely to match the change that actually lands.
- Branch:
feature/m3-d-3-hot-cache-redis-sorted-set - PR title:
feat(memory): Redis sorted-set hot cache with category-conditional recency (m3.D.3)
Working notes
Preferred starting points and open questions — situational, and expected to evolve with further research during implementation.
The simplified hot-cache score formula (confidence/recency/retrieval-weighted, distinct from the full composite score used at query time) must use the category-conditional recency function from 3.D.2 for consistency — otherwise the system would have two different, silently-diverging recency models.
Redis key pattern: {org_id}:hot_memories:{agent_id} — namespaced per the established Redis convention to prevent cross-tenant cache reads.
Success signals
Outcome-oriented signals that the milestone is in good shape. Exact filenames, package layouts, and commands may differ from any sketches above.
- Hot cache score formula reuses
decay_config.CATEGORY_HALF_LIFE_DAYS, not a separate hardcoded 24h constant - Top-50 trim (
ZREMRANGEBYRANK) and TTL refresh behavior verified by test, matching the original spec exactly - Redis keys are
org_id-namespaced per established convention - Repo guards / CI checks still pass
Prerequisites
- Milestone 3.D.2 (composite scoring v2)
Last updated on