Bulk delete memories by filter with dry-run default

[imonroe]

Closes #67

What

POST /api/v1/memories/delete_bulk deletes every memory matching exact-match filters (agent_id, run_id, source, confidence, review_status, optional user_id), so a bad import run or a misbehaving capture agent's writes can be undone in two curl calls instead of scripting one-by-one deletes against the 100-item list page cap:

# dry run (default)
... -d '{"source": "import:chatgpt"}'
# -> {"matched": 412, "deleted": 0, "dry_run": true, "has_more": false, "sample": [...]}

# confirm
... -d '{"source": "import:chatgpt", "confirm": true}'

Safety rails

• Dry-run by default — confirm: false reports the match count and a 10-item sample; nothing is deleted until the caller re-posts with confirm: true.
• No unscoped wipes — at least one filter besides user_id is required (422 otherwise); deleting the entire store through this endpoint is deliberately impossible.
• Bounded — at most 1000 deletions per call (matched/deleted are per-call); has_more tells the caller to loop. This keeps request duration under proxy timeouts.
• Partial-failure honest — if a delete fails mid-loop, the response carries "error": "delete_failed_partway" with the partial count instead of losing it to a 500; deletes are idempotent, so the caller just re-posts.
• History-consistent — deletions go through mem0's Memory.delete per ID, never a raw vector-store filter delete, so mem0's bookkeeping doesn't drift.
• Not exposed over MCP — a destructive filter-delete is an operator/script action, not something a connected agent should reach for (documented in both guides).

Confirmed deletions emit a structlog warning with the filter and counts, and increment a new memories_bulk_deleted_total metric.

Tests

8 new tests across tests/test_rest.py / tests/test_memory.py: unscoped-request 422 (including user_id-only), dry-run deletes nothing, confirm deletes each ID through mem0 (raw vector-store delete asserted unused), filter composition, per-call cap + has_more, 10-item sample cap, partial-failure reporting. Full suite: 175 passed, ruff clean.

Review

Adversarial review surfaced 5 candidates; 4 were fixed (defensive getattr on point IDs, partial-failure handling, matched-is-per-call doc clarification, clearer 422 wording).

https://claude.ai/code/session_01H2Dbh6kD8bseWZZEf7kGhx

---

Generated by Claude Code