AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
fix(backend/copilot): actionable per-UUID reasons on memory forget failures (#13672)
Krzysztof Czerwinskib1eaf9ef94a2
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.pyindex d3196e2693..e47a1eff32 100644--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py@@ -18,9 +18,23 @@ from .models import (ErrorResponse,MemoryForgetCandidatesResponse,MemoryForgetConfirmResponse,+ MemoryForgetFailure,+ MemoryForgetFailureCode,ToolResponseBase,)+# Reason shown when the delete query ran fine but matched no edge — the UUID+# is stale, already deleted, or not a forgettable edge type.+_NO_MATCH_REASON = (+ "No matching edge found — it may already be deleted, or the UUID is not a "+ "forgettable edge (RELATES_TO, MENTIONS, HAS_MEMBER)."+)++# Cap on how many per-UUID failure reasons are inlined into the confirm+# message. Keeps a wholesale-failure batch from blowing past the tool-output+# size threshold (base.py) and losing all detail to truncation.+_MAX_FAILURE_DETAIL = 5+def _now_iso() -> str:"""Current UTC time as an ISO-8601 string for Cypher parameter binding.@@ -38,6 +52,19 @@ def _now_iso() -> str:logger = logging.getLogger(__name__)+def _delete_error_reason(exc: Exception) -> str:+ """Sanitized, actionable reason for a delete query that raised.++ Surfaces the exception type plus its first message arg (e.g. FalkorDB's+ ``Unknown function 'datetime'``) so the model can tell a real query error+ from a plain no-match — but never the full ``repr(exc)``, which can carry+ connection/host details. The complete exception is logged server-side with+ ``exc_info=True`` at each call site for debugging.+ """+ detail = exc.args[0] if exc.args else type(exc).__name__+ return f"Deletion query failed: {type(exc).__name__}: {detail}"++class MemoryForgetSearchTool(BaseTool):"""Search for memories to forget — returns candidates for user confirmation."""@@ -249,30 +276,52 @@ class MemoryForgetConfirmTool(BaseTool):)if hard_delete:- deleted, failed = await _hard_delete_edges(driver, uuids, user_id)+ deleted, failures = await _hard_delete_edges(driver, uuids, user_id)mode = "permanently deleted"else:# User-initiated forget is a *system* retraction, not a world# change. Per Snodgrass bi-temporal semantics, only `expired_at`# is set. `_soft_delete_edges` (which also sets `invalid_at`)# is reserved for the contradiction detector.- deleted, failed = await _retract_edges(driver, uuids, user_id)+ deleted, failures = await _retract_edges(driver, uuids, user_id)mode = "retracted from memory"return MemoryForgetConfirmResponse(- message=(- f"{len(deleted)} memory edge(s) {mode}."- + (f" {len(failed)} failed." if failed else "")- ),+ message=_build_confirm_message(len(deleted), mode, failures),session_id=session.session_id,deleted_uuids=deleted,- failed_uuids=failed,+ failed_uuids=[f.uuid for f in failures],+ failures=failures,)+def _build_confirm_message(+ deleted_count: int, mode: str, failures: list[MemoryForgetFailure]+) -> str:+ """Human/model-readable summary that spells out *why* edges failed.++ A bare "N failed" gives the model nothing to act on (SECRT-2371); listing+ each UUID with its reason lets it retry, hard-delete, or tell the user.++ Only the first ``_MAX_FAILURE_DETAIL`` reasons are inlined: a large batch+ failing wholesale (e.g. a driver outage) would otherwise push the tool+ output past the persist-and-summarize threshold and lose *all* detail. The+ full per-UUID list stays available in the structured ``failures`` field.+ """+ summary = f"{deleted_count} memory edge(s) {mode}."+ if not failures:+ return summary+ shown = failures[:_MAX_FAILURE_DETAIL]+ detail = "; ".join(f"{f.uuid}: {f.reason}" for f in shown)+ remaining = len(failures) - len(shown)+ if remaining > 0:+ detail += f"; …and {remaining} more"+ return f"{summary} {len(failures)} failed — {detail}"++async def _retract_edges(driver, uuids: list[str], user_id: str-) -> tuple[list[str], list[str]]:+) -> tuple[list[str], list[MemoryForgetFailure]]:"""System retraction — set ONLY ``expired_at`` on the edge.Per Snodgrass bi-temporal semantics (see ``dream/dreaming-graphiti.md``@@ -286,9 +335,13 @@ async def _retract_edges(Matches the same edge types as ``_hard_delete_edges`` so that edges ofany type (RELATES_TO, MENTIONS, HAS_MEMBER) can be retracted.++ Returns ``(succeeded_uuids, failures)`` where each failure carries an+ actionable reason (SECRT-2371) — a swallowed error used to look+ identical to a no-op no-match."""- deleted = []- failed = []+ deleted: list[str] = []+ failures: list[MemoryForgetFailure] = []for uuid in uuids:try:records, _, _ = await driver.execute_query(@@ -303,16 +356,28 @@ async def _retract_edges(if records:deleted.append(uuid)else:- failed.append(uuid)- except Exception:+ failures.append(+ MemoryForgetFailure(+ uuid=uuid,+ code=MemoryForgetFailureCode.NO_MATCH,+ reason=_NO_MATCH_REASON,+ )+ )+ except Exception as exc:logger.warning("Failed to retract edge %s for user %s",uuid,user_id[:12],exc_info=True,)- failed.append(uuid)- return deleted, failed+ failures.append(+ MemoryForgetFailure(+ uuid=uuid,+ code=MemoryForgetFailureCode.QUERY_ERROR,+ reason=_delete_error_reason(exc),+ )+ )+ return deleted, failuresasync def _soft_delete_edges(@@ -472,16 +537,19 @@ async def invalidate_entity_direct_neighbors(async def _hard_delete_edges(driver, uuids: list[str], user_id: str-) -> tuple[list[str], list[str]]:+) -> tuple[list[str], list[MemoryForgetFailure]]:"""Permanent removal — delete edges and clean up back-references.Uses graphiti's ``Edge.delete()`` pattern (handles MENTIONS,RELATES_TO, HAS_MEMBER in one query). Does NOT delete orphanedentity nodes — they may have summaries, embeddings, or futureconnections. Cleans up episode ``entity_edges`` back-references.++ Returns ``(succeeded_uuids, failures)`` with a per-UUID reason on each+ failure (SECRT-2371)."""- deleted = []- failed = []+ deleted: list[str] = []+ failures: list[MemoryForgetFailure] = []for uuid in uuids:try:# Use WITH to capture the uuid before DELETE so we don't@@ -497,7 +565,13 @@ async def _hard_delete_edges(uuid=uuid,)if not records:- failed.append(uuid)+ failures.append(+ MemoryForgetFailure(+ uuid=uuid,+ code=MemoryForgetFailureCode.NO_MATCH,+ reason=_NO_MATCH_REASON,+ )+ )continue# Edge was deleted — report success regardless of cleanup outcome.deleted.append(uuid)@@ -518,12 +592,18 @@ async def _hard_delete_edges(user_id[:12],exc_info=True,)- except Exception:+ except Exception as exc:logger.warning("Failed to hard-delete edge %s for user %s",uuid,user_id[:12],exc_info=True,)- failed.append(uuid)- return deleted, failed+ failures.append(+ MemoryForgetFailure(+ uuid=uuid,+ code=MemoryForgetFailureCode.QUERY_ERROR,+ reason=_delete_error_reason(exc),+ )+ )+ return deleted, failuresdiff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.pyindex 3ea13e6960..1c8aede4f1 100644--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py@@ -4,13 +4,22 @@ from unittest.mock import AsyncMockimport pytest+from backend.copilot.model import ChatSessionfrom backend.copilot.tools.graphiti_forget import (+ _MAX_FAILURE_DETAIL,+ MemoryForgetConfirmTool,+ _build_confirm_message,_hard_delete_edges,_retract_edges,_soft_delete_edges,invalidate_entity_direct_neighbors,mark_edges_superseded,)+from backend.copilot.tools.models import (+ MemoryForgetConfirmResponse,+ MemoryForgetFailure,+ MemoryForgetFailureCode,+)class TestSoftDeleteOverReportsSuccess:@@ -78,7 +87,9 @@ class TestHardDeleteBasicFlow:driver, ["nonexistent-uuid"], "test-user")assert deleted == []- assert failed == ["nonexistent-uuid"]+ assert [f.uuid for f in failed] == ["nonexistent-uuid"]+ assert failed[0].reason # actionable, non-empty reason+ assert failed[0].code == MemoryForgetFailureCode.NO_MATCH# Only the delete query should run — cleanup skippedassert driver.execute_query.call_count == 1@@ -103,6 +114,22 @@ class TestRetractEdgesSnodgrass:# Critical contract: must NOT touch invalid_atassert "invalid_at" not in query+ @pytest.mark.asyncio+ async def test_retract_never_uses_falkordb_incompatible_datetime(self) -> None:+ """Root cause of SECRT-2371: the shipped soft delete used Cypher's+ no-arg ``datetime()``, which FalkorDB rejects with "Unknown function+ 'datetime'". The raised error was swallowed, so every soft delete+ reported "0 invalidated, N failed" while hard delete (no datetime())+ worked. The timestamp must be bound from Python as ``$now``."""+ driver = AsyncMock()+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)++ await _retract_edges(driver, ["u1"], "test-user")++ query = driver.execute_query.call_args.args[0]+ assert "datetime()" not in query+ assert "$now" in query+@pytest.mark.asyncioasync def test_retract_reports_failure_on_no_match(self) -> None:driver = AsyncMock()@@ -110,7 +137,174 @@ class TestRetractEdgesSnodgrass:deleted, failed = await _retract_edges(driver, ["missing"], "test-user")assert deleted == []- assert failed == ["missing"]+ assert [f.uuid for f in failed] == ["missing"]+ # No-match must carry an actionable reason, not a bare count.+ assert failed[0].reason+ assert failed[0].code == MemoryForgetFailureCode.NO_MATCH+++class TestForgetFailuresAreActionable:+ """SECRT-2371: soft delete must not fail silently. Every failure — whether+ the query errored or matched nothing — has to carry a per-UUID reason so+ the model can act (retry, hard-delete, or tell the user) instead of seeing+ a bare "0 invalidated, N failed"."""++ @pytest.mark.asyncio+ async def test_retract_surfaces_query_exception_reason(self) -> None:+ driver = AsyncMock()+ # Reproduces the original root cause: FalkorDB rejected the no-arg+ # Cypher datetime() with "Unknown function 'datetime'". The exception+ # used to be swallowed, leaving the model no clue why it failed.+ driver.execute_query.side_effect = RuntimeError("Unknown function 'datetime'")++ deleted, failed = await _retract_edges(driver, ["u1"], "test-user")++ assert deleted == []+ assert [f.uuid for f in failed] == ["u1"]+ assert "datetime" in failed[0].reason+ assert failed[0].code == MemoryForgetFailureCode.QUERY_ERROR++ @pytest.mark.asyncio+ async def test_retract_distinguishes_no_match_from_error(self) -> None:+ driver = AsyncMock()+ # First uuid errors, second matches nothing.+ driver.execute_query.side_effect = [+ RuntimeError("boom"),+ ([], None, None),+ ]++ deleted, failed = await _retract_edges(+ driver, ["errored", "missing"], "test-user"+ )++ assert deleted == []+ by_uuid = {f.uuid: f for f in failed}+ assert "boom" in by_uuid["errored"].reason+ # No-match reason must be distinct from the error reason.+ assert by_uuid["missing"].reason != by_uuid["errored"].reason+ # ...and the machine-switchable codes distinguish them too.+ assert by_uuid["errored"].code == MemoryForgetFailureCode.QUERY_ERROR+ assert by_uuid["missing"].code == MemoryForgetFailureCode.NO_MATCH++ @pytest.mark.asyncio+ async def test_hard_delete_surfaces_query_exception_reason(self) -> None:+ driver = AsyncMock()+ driver.execute_query.side_effect = RuntimeError("edge locked")++ deleted, failed = await _hard_delete_edges(driver, ["u1"], "test-user")++ assert deleted == []+ assert [f.uuid for f in failed] == ["u1"]+ assert "edge locked" in failed[0].reason+ assert failed[0].code == MemoryForgetFailureCode.QUERY_ERROR++ @pytest.mark.asyncio+ async def test_confirm_tool_reports_reasons_in_response(self, monkeypatch) -> None:+ """End to end: a soft delete that matches nothing must return the+ per-UUID reason in both the structured `failures` field and the+ human-readable message — not a bare "0 invalidated, 1 failed"."""++ async def _enabled(_user_id: str) -> bool:+ return True++ driver = AsyncMock()+ driver.execute_query.return_value = ([], None, None)+ client = type("Client", (), {"graph_driver": driver})()++ async def _get_client(_group_id: str):+ return client++ monkeypatch.setattr(+ "backend.copilot.tools.graphiti_forget.is_enabled_for_user", _enabled+ )+ monkeypatch.setattr(+ "backend.copilot.tools.graphiti_forget.get_graphiti_client", _get_client+ )++ session = ChatSession.new("user-abc", dry_run=False)+ response = await MemoryForgetConfirmTool()._execute(+ "user-abc", session, uuids=["missing-uuid"]+ )++ assert isinstance(response, MemoryForgetConfirmResponse)+ assert response.deleted_uuids == []+ assert [f.uuid for f in response.failures] == ["missing-uuid"]+ assert response.failed_uuids == ["missing-uuid"]+ assert response.failures[0].code == MemoryForgetFailureCode.NO_MATCH+ # The reason must reach the model-visible message, not just the count.+ assert response.failures[0].reason in response.message+ assert "missing-uuid" in response.message++ @pytest.mark.asyncio+ async def test_confirm_tool_mixed_batch_reports_both(self, monkeypatch) -> None:+ """A batch where some UUIDs delete and some fail must co-populate+ `deleted_uuids` and `failures`, and the message must carry BOTH the+ success count and the per-UUID failure detail."""++ async def _enabled(_user_id: str) -> bool:+ return True++ driver = AsyncMock()+ # _retract_edges runs one query per UUID: first matches, second doesn't.+ driver.execute_query.side_effect = [+ ([{"uuid": "kept"}], None, None),+ ([], None, None),+ ]+ client = type("Client", (), {"graph_driver": driver})()++ async def _get_client(_group_id: str):+ return client++ monkeypatch.setattr(+ "backend.copilot.tools.graphiti_forget.is_enabled_for_user", _enabled+ )+ monkeypatch.setattr(+ "backend.copilot.tools.graphiti_forget.get_graphiti_client", _get_client+ )++ session = ChatSession.new("user-abc", dry_run=False)+ response = await MemoryForgetConfirmTool()._execute(+ "user-abc", session, uuids=["kept", "gone"]+ )++ assert isinstance(response, MemoryForgetConfirmResponse)+ assert response.deleted_uuids == ["kept"]+ assert [f.uuid for f in response.failures] == ["gone"]+ # Two-part message: success half + failure detail half.+ assert "1 memory edge(s) retracted from memory." in response.message+ assert "1 failed" in response.message+ assert "gone" in response.message+++class TestBuildConfirmMessage:+ """`_build_confirm_message` formatting: the no-failure early return, the+ two-part success+failure string, and the bounded detail (thread: a driver+ outage failing every UUID must not blow the tool output past its size+ threshold and lose all detail)."""++ def test_no_failures_returns_summary_only(self) -> None:+ message = _build_confirm_message(3, "retracted from memory", [])+ assert message == "3 memory edge(s) retracted from memory."++ def test_caps_inlined_detail_and_notes_remainder(self) -> None:+ overflow = _MAX_FAILURE_DETAIL + 4+ failures = [+ MemoryForgetFailure(+ uuid=f"uuid-{i}",+ code=MemoryForgetFailureCode.NO_MATCH,+ reason="x" * 120,+ )+ for i in range(overflow)+ ]++ message = _build_confirm_message(0, "retracted from memory", failures)++ # Full count is reported, but only the first N reasons are inlined.+ assert f"{overflow} failed" in message+ assert f"…and {overflow - _MAX_FAILURE_DETAIL} more" in message+ assert message.count("uuid-") == _MAX_FAILURE_DETAIL+ # Bounded regardless of batch size — cannot grow with the input.+ assert len(message) < _MAX_FAILURE_DETAIL * 300class TestSoftDeleteContradictionPath:diff --git a/autogpt_platform/backend/backend/copilot/tools/models.py b/autogpt_platform/backend/backend/copilot/tools/models.pyindex ebd9a2de57..8dfba90b7d 100644--- a/autogpt_platform/backend/backend/copilot/tools/models.py+++ b/autogpt_platform/backend/backend/copilot/tools/models.py@@ -984,12 +984,38 @@ class MemoryForgetCandidatesResponse(ToolResponseBase):candidates: list[dict[str, str]] = Field(default_factory=list)+class MemoryForgetFailureCode(str, Enum):+ """Stable, machine-switchable reason a forget delete failed.++ The frontend/model can branch on this code (retry vs. give up) without+ parsing the free-text ``reason``. New codes may be added over time, so+ consumers must tolerate unknown values.+ """++ NO_MATCH = "no_match"+ QUERY_ERROR = "query_error"+++class MemoryForgetFailure(BaseModel):+ """One edge that could not be deleted, with an actionable reason.++ Surfaced so the assistant (and user) can tell *why* a delete failed —+ e.g. the edge was not found vs. the query itself errored — instead of a+ bare "N failed" count that gives the model nothing to act on.+ """++ uuid: str+ code: MemoryForgetFailureCode+ reason: str++class MemoryForgetConfirmResponse(ToolResponseBase):"""Response after deleting specific memory edges."""type: ResponseType = ResponseType.MEMORY_FORGET_CONFIRMdeleted_uuids: list[str] = Field(default_factory=list)failed_uuids: list[str] = Field(default_factory=list)+ failures: list[MemoryForgetFailure] = Field(default_factory=list)# --- Planning ---diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.jsonindex 27d192d2e9..f077f82baa 100644--- a/autogpt_platform/frontend/src/app/api/openapi.json+++ b/autogpt_platform/frontend/src/app/api/openapi.json@@ -19356,6 +19356,11 @@"items": { "type": "string" },"type": "array","title": "Failed Uuids"+ },+ "failures": {+ "items": { "$ref": "#/components/schemas/MemoryForgetFailure" },+ "type": "array",+ "title": "Failures"}},"type": "object",@@ -19363,6 +19368,23 @@"title": "MemoryForgetConfirmResponse","description": "Response after deleting specific memory edges."},+ "MemoryForgetFailure": {+ "properties": {+ "uuid": { "type": "string", "title": "Uuid" },+ "code": { "$ref": "#/components/schemas/MemoryForgetFailureCode" },+ "reason": { "type": "string", "title": "Reason" }+ },+ "type": "object",+ "required": ["uuid", "code", "reason"],+ "title": "MemoryForgetFailure",+ "description": "One edge that could not be deleted, with an actionable reason.\n\nSurfaced so the assistant (and user) can tell *why* a delete failed —\ne.g. the edge was not found vs. the query itself errored — instead of a\nbare \"N failed\" count that gives the model nothing to act on."+ },+ "MemoryForgetFailureCode": {+ "type": "string",+ "enum": ["no_match", "query_error"],+ "title": "MemoryForgetFailureCode",+ "description": "Stable, machine-switchable reason a forget delete failed.\n\nThe frontend/model can branch on this code (retry vs. give up) without\nparsing the free-text ``reason``. New codes may be added over time, so\nconsumers must tolerate unknown values."+ },"MemoryOverview": {"properties": {"user_id": { "type": "string", "title": "User Id" },