feat(agent-memory): Phase 3 — forget / forgetByScope

[jamby77]

Agent Memory — Phase 3: forget / forgetByScope

Stacked on #249 (Phase 2).

What's new

• forget(id) → DEL {name}:mem:{id}; idempotent (returns whether the memory existed).
• forgetByScope(scope & {tags?}) → finds matches via an escaped scope/tag FT.SEARCH filter, DELs them in batches, returns the count. Throws when no scope field or tag is given (prevents an accidental delete-everything).
• Extracted shared buildScopeFilter (used by both recall and forget); escapeTag neutralizes glob chars so a threadId of '*' matches literally, not everything.

Design note

The plan says "SCAN-matches scope/tags", but scope/tags are HASH fields (TAG-indexed), not part of the key ({name}:mem:{uuid}) — a key SCAN can't filter on them. So forgetByScope uses an FT.SEARCH filter query, which is the correct mechanism.

Tests

27 unit tests; tsc --noEmit + prettier clean.

Review-driven change

• Batched pagination instead of a 10000-row cap — the first pass deleted only the first 10k matches and reported that as success (silent truncation for large scopes). Now loops FT.SEARCH(LIMIT 0 500) → DEL batch → repeat, with a seen set so it terminates even under index-update lag.

Next

Phase 4 (recall reinforcement — bump lastAccessedAt/accessCount on recalled items).

---

Note

Medium Risk
Introduces destructive bulk deletes against persisted agent memory, though scoped filters, empty-scope errors, and batch-cap warnings reduce accidental data loss risk.

Overview
Adds memory deletion to MemoryStore: forget(id) removes one hash via DEL and returns whether it existed; forgetByScope finds memories with the same escaped scope/tag FT.SEARCH filter used for recall, deletes them in 500-key batches (loop until empty or no progress), and returns the total deleted count.

buildScopeFilter is extracted from buildRecallQuery so recall and forget share identical filter semantics (including escapeTag for literal * etc.). forgetByScope rejects an empty scope so callers cannot wipe the index by accident; hitting the 10k-batch safety cap logs a warning when more matches may remain.

New unit tests cover idempotency, filter shape, glob escaping, pagination, and the cap warning.

^{Reviewed by Cursor Bugbot for commit 8ab239a. 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.

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

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