feat(agent-memory): Phase 5 — eviction & TTL

[jamby77]

Stacked on #251 (Phase 4 — recall reinforcement).

What

Phase 5 of @betterdb/agent-memory: capacity-based eviction and TTL writes.

• selectEvictions() (pure): selects the lowest-ranked keys to drop so maxItems remain. Ranks by a blend of importance and last-access recency — the recall weights minus similarity, renormalized — lowest first, ties broken toward the older last-access.
• recencyDecay() extracted from compositeScore so recall ranking and eviction share one true half-life decay.
• TTL writes: remember(content, { ttl }) sets the hash and its expiry atomically via MULTI/HSET/EXPIRE/EXEC; a non-positive/absent ttl writes a durable HSET.
• Capacity enforcement: when maxItemsPerScope is configured, each write runs a count-first probe (cheap LIMIT 0 0) and only fetches candidates when over capacity, then evicts the excess and increments evictions in {name}:__mem_stats. Best-effort — a failed eviction pass never rejects an already-durable write.

Design notes

• Eviction recency uses last_accessed_at (fed by reinforcement); recall recency uses created_at — deliberate split per spec.
• Selection is exact while a scope fits EVICTION_SCAN_LIMIT; larger scopes evict from the scanned window and reclaim the remainder on subsequent writes.
• TTL is a hard expiry (per spec "expire naturally") — reinforcement feeds recency/capacity-eviction, not TTL extension.

Tests

• selectEvictions.test.ts — capacity boundary, drop count, importance- vs recency-driven ordering, weight-dominance, tie-breaks.
• MemoryStore.eviction.test.ts — atomic TTL sequence, durable/non-positive-ttl paths, over/under-capacity eviction + counter, scope-filtered query, unconfigured no-op, best-effort failure isolation.

47/47 package tests green · tsc --noEmit clean · prettier clean.

---

Note

Medium Risk
Deletes stored memories on write when over capacity and changes remember's Redis command pattern; failures are isolated but eviction is destructive and approximate beyond the scan window.

Overview
Adds TTL and per-scope capacity limits to @betterdb/agent-memory MemoryStore.remember.

remember now accepts optional ttl (seconds). Positive TTL persists the hash and EXPIRE in one MULTI/EXEC; missing or non-positive TTL stays a plain durable HSET. After each write, optional maxItemsPerScope runs a best-effort capacity pass: a cheap FT.SEARCH count on the same scope/tag filter as recall/forget, then eviction only when over limit. Eviction uses new selectEvictions(), ranking by importance plus last_accessed_at recency (recall weights minus similarity, shared recencyDecay()), deletes losers, and increments {name}:__mem_stats evictions`. Enforcement failures are swallowed so writes still succeed.

Tests cover TTL command sequences, scope/tag partitioning, under-capacity no-ops, eviction selection, and write isolation when search fails.

^{Reviewed by Cursor Bugbot for commit a820313. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e4646ec. Configure here.}