Summary

Adds a new mempalace clean subcommand for reclaiming palace space and starting projects over. It removes drawers at two granularities — an entire wing, or a specific room within a wing — and keeps the mempalace_drawers and mempalace_compressed collections in lockstep so compressed copies never go stale after a cleanup.

Motivation

Today there is no first-class way to remove memories once a project is done. Users either re-mine forever or hand-edit ChromaDB. The new subcommand gives a safe, auditable way to scrub scoped memory without touching the rest of the palace.

UX

mempalace clean --wing my_app                    # remove all drawers in a wing
mempalace clean --wing my_app --room costs       # remove all drawers in one room
mempalace clean --wing my_app --dry-run          # preview counts, no changes
mempalace clean --wing my_app --yes              # skip interactive confirmation

Sample output:

=======================================================
  MemPalace Clean
=======================================================

  Palace: /home/user/.mempalace/palace
  Target: wing 'my_app', room 'backend'
  Drawers to remove:    12
  Compressed to remove: 12

  Delete 12 drawer(s) from wing 'my_app', room 'backend'? [y/N] y

  Removed 12 drawer(s) from wing 'my_app', room 'backend'.
  Removed 12 compressed drawer(s).

  Note: the knowledge graph (~/.mempalace/knowledge_graph.sqlite3) is not touched by clean.

Design decisions

• --wing is required. No implicit "clean everything" — refuses to run without a wing filter. This is intentional: the cost of an accidental full wipe is very high.
• Single flag per scope. Only --wing and --room. I considered splitting into --room (clear contents) vs --del-room (remove the room itself), but rooms and wings are metadata-only in mempalace today — they exist only as fields on drawer metadata, not as first-class records. Once the last drawer in a room is deleted the room disappears from list_rooms automatically, so "clear contents" and "delete room" would produce identical observable state. Added a registry was deemed scope creep.
• Knowledge graph left untouched. KG facts in ~/.mempalace/knowledge_graph.sqlite3 do not carry a wing field, so they can't be filtered cleanly by wing without false positives. The --help text explicitly notes this and the runtime output reminds the user after every cleanup.
• Compressed collection cleaned in lockstep. mempalace_compressed shares drawer IDs with mempalace_drawers. Leaving compressed copies behind after a wing/room cleanup would be a correctness bug, so both collections are filtered and deleted in the same operation.
• Single WAL entry per cleanup. A clean_wing or clean_room record is appended to ~/.mempalace/wal/write_log.jsonl with {wing, room, drawers_deleted, compressed_deleted}. Per-drawer logging was rejected as noisy for bulk ops.
• Interactive confirmation by default. Prompts [y/N] with a count summary before deleting. --yes skips the prompt for scripting. --dry-run shows counts and exits without touching anything.
• Safe degraded operation. If mempalace_compressed doesn't exist (palace was never compressed), the cleanup proceeds against mempalace_drawers only without error.

Files changed

• mempalace/palace.py — added _build_where, count_drawers, delete_drawers helpers (+34 lines). Keeps the CLI layer thin and makes the primitives reusable for a future MCP clean tool.
• mempalace/cli.py — added cmd_clean, the clean subparser, and a dispatch entry. Docstring updated with the new command in the help epilog (+142 lines).
• tests/test_clean.py — 15 new tests (+221 lines).

Tests

Added tests/test_clean.py with 15 tests covering:

Primitive layer (palace.count_drawers / delete_drawers):

• Counting by wing
• Counting by wing + room
• Deleting by wing leaves other wings untouched
• Deleting by room leaves sibling rooms untouched
• Nothing-to-delete returns zero

CLI layer (cli.cmd_clean):

• Cleaning a wing removes matching drawers from both mempalace_drawers and mempalace_compressed
• Cleaning a room scopes correctly and preserves sibling rooms
• --dry-run makes zero changes
• No-match scenario prints "Nothing to clean" and exits 0
• Interactive n at the prompt cancels the delete
• Interactive y at the prompt proceeds
• Works without a compressed collection present
• Writes a clean_room WAL entry with the expected counts
• Missing --wing flag exits non-zero
• Missing palace directory exits non-zero with a clear message

Test results

$ python3 -m pytest -x -q
549 passed, 106 deselected in 8.83s

All 549 tests in the suite pass (15 new, 534 existing). No regressions.

Test plan

• python3 -m pytest tests/test_clean.py -v passes locally
• python3 -m pytest -q — full suite still green
• python3 -m mempalace clean --help shows the expected usage
• Dry-run against a real palace: mempalace clean --wing <some-wing> --dry-run reports accurate counts
• Actual cleanup against a disposable palace, then verify via mempalace status or mempalace_list_rooms that the wing/room is gone
• Confirm a WAL entry landed in ~/.mempalace/wal/write_log.jsonl with operation: clean_wing (or clean_room) and correct counts
• If the palace has compressed drawers, confirm mempalace_compressed was cleaned in lockstep

Notes for reviewers

• The "knowledge graph not touched" behavior is called out in both --help text and runtime output so users aren't surprised. If you want KG cleanup later, it would need a new wing tag on KG triples — out of scope for this PR.
• delete_drawers uses ChromaDB's native delete(where=...). The _build_where helper produces either {"wing": X} or {"$and": [{"wing": X}, {"room": Y}]} depending on scope.
• Commit is authored via the brandonhon GitHub noreply email for email-privacy compliance.