fix(memory): guard against self-supersede hiding recalled preferences (#2452)

A saved priority-sender preference could end up with `superseded_by`
pointing at **its own id** — the update-consolidation path dedups
identical content back into the same row and then marked that row
superseded — so `recall(category=preference)` returned **0 results**.
Asking "what priority-sender rules do I have saved?" in a new session
answered "none" even though the rule was saved. Now the consolidation
path only supersedes when a genuinely new row was created, and the
memory store hard-rejects a self-supersede, so saved preferences stay
recallable.

## Test plan
- [x] Unit — `tests/unit/test_memory_store.py` +
`tests/unit/test_memory_mixin.py` → **507 passed** (incl. the two
regression tests)
- [x] Real-world, Linux + macOS — reproduced the exact dedup-collapse
trigger through the real installed package (log shows `knowledge deduped
id=…` — same id), then `get_by_category("preference")` returns the pref
with `superseded_by: None`; sqlite `SELECT id FROM knowledge WHERE
superseded_by = id` → `[]`
- [x] Agent UI, Linux + macOS — in a brand-new session, asked "what
priority-sender rules do I have saved?" → the RECALL tool fired and the
agent answered with the planted preference `zephyr-otter-9x@example.com`

**Real-world Agent UI evidence** (planted, unguessable fact
`zephyr-otter-9x@example.com`):

![macOS Agent UI — recall in a new
session](https://raw.githubusercontent.com/amd/gaia/m59-autofix-evidence/testing/2452/2446_macos_ui_recall.png)
![Linux Agent UI — recall in a new
session](https://raw.githubusercontent.com/amd/gaia/m59-autofix-evidence/testing/2452/2446_linux_ui_recall.png)

Closes #2446

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: github-actions[bot]

src/gaia/agents/base/memory.py

@@ -1364,9 +1364,13 @@ def _execute_extraction_operations(
                         source="llm_extract",
                         context=self._memory_context,
                     )
-                    # Mark old as superseded and remove from FAISS
-                    store.update(old_id, superseded_by=new_id)
-                    self._faiss_remove(old_id)
+                    # Only supersede when store() actually created a new row.
+                    # Dedup can collapse near-identical content back into old_id,
+                    # which would point superseded_by at the row itself and hide
+                    # it from every active query (recall, get_by_category).
+                    if new_id != old_id:
+                        store.update(old_id, superseded_by=new_id)
+                        self._faiss_remove(old_id)
                     # Embed the new item
                     try:
                         vec = self._embed_text(op["content"])

src/gaia/agents/base/memory_store.py

@@ -1324,6 +1324,15 @@ def update(
                 When set, this item is considered historical/inactive and will be
                 excluded from active queries (search, get_by_*, system prompt).
         """
+        # A row may never supersede itself — that would set superseded_by to its
+        # own id and hide it from every active query (recall, get_by_category).
+        if superseded_by is not None and superseded_by == knowledge_id:
+            raise ValueError(
+                f"update(): superseded_by ({superseded_by}) must not equal the "
+                f"row's own id; a self-supersede makes the row unrecallable. "
+                f"Only supersede when a genuinely new row was created."
+            )
+
         # Normalize empty strings to None — same semantics as store().
         # An empty-string entity or domain would differ from NULL in SQL and
         # break entity-scoped dedup, index filtering, and stats queries.

tests/unit/test_memory_mixin.py

@@ -2371,6 +2371,40 @@ def test_extraction_drops_privileged_categories(self, extract_host):
         assert "permission" not in cats
         assert "system" not in cats
 
+    def test_update_dedup_does_not_self_supersede(self, extract_host):
+        """Update-consolidation over near-identical content stays recallable.
+
+        Regression for #2446: store() dedups near-identical content back into
+        the same row and returns old_id; the update path must NOT then mark the
+        row as superseded_by=old_id, which would hide it from recall.
+        """
+        extract_host._memory_context = "global"
+        store = extract_host._memory_store
+
+        old_id = store.store(
+            category="preference",
+            content="Prioritize email from alice@example.com",
+            source="llm_extract",
+            context="global",
+        )
+
+        # An "update" whose content dedups back into the same row.
+        ops = [
+            {
+                "op": "update",
+                "knowledge_id": old_id,
+                "category": "preference",
+                "content": "Prioritize email from alice@example.com",
+            }
+        ]
+        existing_items = [{"id": old_id, "category": "preference", "confidence": 0.4}]
+        extract_host._execute_extraction_operations(ops, existing_items)
+
+        # The preference must still be recallable — not self-superseded.
+        results = store.get_by_category("preference", context="global")
+        assert any(r["id"] == old_id for r in results)
+        assert all(r["superseded_by"] is None for r in results)
+
     def test_after_process_query_stores_conversation(self, extract_host):
         """_after_process_query() stores both user and assistant turns."""
         extract_host._memory_session_id = "test-session-extraction"

tests/unit/test_memory_store.py

@@ -165,6 +165,23 @@ def test_update_returns_false_for_nonexistent_id(self, store):
         fake_id = str(uuid.uuid4())
         assert store.update(fake_id, content="new content") is False
 
+    def test_update_rejects_self_supersede(self, store):
+        """update() refuses to point superseded_by at the row's own id.
+
+        A self-supersede would hide the row from every active query
+        (recall, get_by_category) — see issue #2446.
+        """
+        entry_id = store.store(
+            category="preference",
+            content="Prioritize email from alice@example.com",
+        )
+        with pytest.raises(ValueError, match="must not equal"):
+            store.update(entry_id, superseded_by=entry_id)
+
+        # The row must remain recallable — the rejected update changed nothing.
+        results = store.get_by_category("preference")
+        assert any(r["id"] == entry_id for r in results)
+
     def test_delete_entry(self, store):
         """delete() removes an entry."""
         entry_id = store.store(category="fact", content="Temporary fact")
@@ -3963,13 +3980,15 @@ def test_get_all_knowledge_excludes_superseded_by_default(self, store):
 
     def test_get_all_knowledge_includes_superseded_when_requested(self, store):
         """get_all_knowledge(include_superseded=True) includes superseded items."""
+        # Contents must be distinct enough to NOT dedup into one row, else
+        # store() returns the same id and the supersede would be a self-supersede.
         old_id = store.store(
             category="fact",
-            content="Superseded item included when requested test",
+            content="Historical note about the old deployment target",
         )
         new_id = store.store(
             category="fact",
-            content="Active item included when requested test",
+            content="Fresh replacement pointing at a brand new value",
         )
         store.update(old_id, superseded_by=new_id)