feat(memory): reversible curation — edit / invalidate memory units

[nicoloboschi]

Summary

Adds reversible memory curation — edit and invalidate individual memory units — implementing the design in #1951.

Closes #1951. Supersedes the bare valid_to approach of #1878/#1395 (and answers the long-standing #1391/#1094 "let me fix/remove a bad memory" requests).

Endpoint

PATCH /v1/default/banks/{bank_id}/memories/{memory_id} — one endpoint, three reversible operations:

• edit ({text, reason?}): correct the fact text, re-embed, drop derived observations + links, re-consolidate; previous text saved to history.
• invalidate ({state:"invalidated", reason?}): retire the fact — excluded from recall/consolidation/graph. Reversible.
• revert ({state:"valid"}): bring it back, restore its entity associations, re-consolidate.

Only world/experience facts can be curated — observations are derived and regenerate from their sources.

Design: invalidation moves the row to a separate table

Rather than flag rows in place, invalidation moves a fact out of memory_units into a sibling invalidated_memory_units archive. The recall hot-path stays pristine — no state predicate on any read path, and there's zero chance an invalidated row leaks into results because it simply isn't in the table the queries read. (We evaluated an in-place state column; the team chose the separate table for the structural no-leak guarantee and a clean hot-path, accepting a two-table schema and a heavier — but rare — revert.)

• invalidate: snapshot the unit's entity ids → INSERT … SELECT into the archive → DELETE from memory_units (the cascade prunes its links + entity associations; dependent observations are re-derived). The embedding travels with the archived row.
• revert: move the row back, restore the entity associations from the snapshot, and re-consolidate. Links are rebuilt by graph maintenance. Lossless.
• edit: in place on the live row.

Why not just retain a contradicting fact? Because consolidation only reconciles in-stream contradictions (e.g. "likes BMW" → later "likes Toyota") — it can't help when a fact is simply wrong, or stale with nothing to contradict it (a decommissioned server, a tool that was fixed). Those are exactly what edit/invalidate are for. Systematic extraction problems should still be fixed at the mission level and reprocessed.

Schema

Migration c9a1b2d3e4f5 creates invalidated_memory_units via LIKE memory_units INCLUDING DEFAULTS (so a row round-trips verbatim) plus invalidation_reason, invalidated_at, and an entity_ids snapshot; FK to documents ON DELETE CASCADE. Oracle baseline gets the table. memory_units is unchanged — no new column, no new index, no read-path filter. delete_bank and backup/restore (BACKUP_TABLES) cover the new table.

Surfacing / control plane / clients

• get_memory_unit and /memories/list report state/invalidation_reason/invalidated_at; list reads the archive for ?state=invalidated (default lists live facts).
• Control plane: PATCH proxy route, lib/api.ts updateMemory() + list state filter, memory-detail-panel state badge + Invalidate/Restore button, i18n keys.
• Regenerated Python/TS/Go SDKs + OpenAPI (PATCH only; no schema surface change since); Rust regenerates at build time.
• New docs page developer/curation.md.

Test plan

• test_memory_curation.py (engine): invalidate moves to archive (links + derived observations pruned, surviving sources reset, embedding archived), revert moves back + restores entity associations, edit + history, observation/invalidated-edit guards, list state filter, recall exclusion.
• test_curation_http.py (HTTP): PATCH invalidate → GET → revert; 404 on missing; 422 on empty body.
• Regression: observation-invalidation, graph-maintenance, recall, backup/restore guard (test_backup_tables_covers_entire_schema) all pass.
• ruff + ty + lint clean; single alembic head; migration-shape lint passes.
• Rebased onto current origin/main (clean; read-path files reconcile exactly, generated SDKs/OpenAPI regenerated).
• @pytest.mark.hs_llm_core consolidation tests need a real LLM key (pass in CI).

🤖 Generated with Claude Code