feat(sdk, docs): expose agent_custom_instructions for agent-scoped extraction (#6809)

tests/test_client.py

@@ -440,3 +440,51 @@ class TestValidateApiKeyHttpError:
 
         assert not isinstance(exc_info.value, requests.exceptions.JSONDecodeError)
         assert "Error:" in str(exc_info.value)
+
+
+class TestAddAgentCustomInstructions:
+    """Per-request override of the project-level setting, forwarded to the add payload."""
+
+    def _mock_add(self, client):
+        response = MagicMock()
+        response.json.return_value = {"results": []}
+        response.raise_for_status.return_value = None
+        client.client.post.return_value = response
+        return response
+
+    def test_kwarg_reaches_the_add_payload(self, mock_memory_client):
+        self._mock_add(mock_memory_client)
+
+        mock_memory_client.add(
+            "hello",
+            filters={"agent_id": "a1"},
+            agent_custom_instructions="remember tool failures",
+        )
+
+        _, kwargs = mock_memory_client.client.post.call_args
+        assert kwargs["json"]["agent_custom_instructions"] == "remember tool failures"
+
+    def test_typed_option_reaches_the_add_payload(self, mock_memory_client):
+        from mem0.client.types import AddMemoryOptions
+
+        self._mock_add(mock_memory_client)
+
+        mock_memory_client.add(
+            "hello",
+            AddMemoryOptions(
+                filters={"agent_id": "a1"},
+                agent_custom_instructions="remember tool failures",
+            ),
+        )
+
+        _, kwargs = mock_memory_client.client.post.call_args
+        assert kwargs["json"]["agent_custom_instructions"] == "remember tool failures"
+
+    def test_absent_when_not_passed(self, mock_memory_client):
+        """Callers that don't use the feature send an unchanged payload."""
+        self._mock_add(mock_memory_client)
+
+        mock_memory_client.add("hello", filters={"user_id": "u1"})
+
+        _, kwargs = mock_memory_client.client.post.call_args
+        assert "agent_custom_instructions" not in kwargs["json"]

tests/test_project.py

@@ -3,8 +3,8 @@ parameter-passthrough surface.
 
 Verifies the kwarg → JSON payload mapping for every supported field
 (``custom_instructions``, ``custom_categories``, ``multilingual``,
-``decay``), the ValueError when no field is provided, and the
-URL/method shape. The HTTP layer is mocked.
+``decay``, ``agent_custom_instructions``), the ValueError when no field
+is provided, and the URL/method shape. The HTTP layer is mocked.
 """
 
 from unittest.mock import MagicMock, patch
@@ -84,6 +84,50 @@ class TestProjectUpdateDecay:
         assert args[0] == "/api/v1/orgs/organizations/org1/projects/proj1/"
 
 
+class TestProjectUpdateAgentCustomInstructions:
+    def test_agent_custom_instructions_sent_in_payload(self, project):
+        proj, http = project
+        proj.update(agent_custom_instructions="remember tool failures")
+        assert _patch_payload(http) == {"agent_custom_instructions": "remember tool failures"}
+
+    def test_agent_custom_instructions_alone_satisfies_the_guard(self, project):
+        """It is a standalone field, so setting only it must not raise."""
+        proj, http = project
+        proj.update(agent_custom_instructions="remember tool failures")
+        assert http.patch.called
+
+    def test_empty_string_round_trips_to_clear_the_field(self, project):
+        """An empty string must survive the ``is not None`` filter, not be dropped as falsy."""
+        proj, http = project
+        proj.update(agent_custom_instructions="")
+        assert _patch_payload(http) == {"agent_custom_instructions": ""}
+
+    def test_combined_with_custom_instructions(self, project):
+        """Both sets in one PATCH: the split-instruction configuration."""
+        proj, http = project
+        proj.update(
+            custom_instructions="remember user preferences",
+            agent_custom_instructions="remember tool failures",
+        )
+        assert _patch_payload(http) == {
+            "custom_instructions": "remember user preferences",
+            "agent_custom_instructions": "remember tool failures",
+        }
+
+    def test_omitted_when_none(self, project):
+        """Callers that don't pass it must send an unchanged payload."""
+        proj, http = project
+        proj.update(custom_instructions="be concise")
+        payload = _patch_payload(http)
+        assert payload == {"custom_instructions": "be concise"}
+        assert "agent_custom_instructions" not in payload
+
+    def test_no_args_raises_with_agent_instructions_in_message(self, project):
+        proj, _ = project
+        with pytest.raises(ValueError, match=r"agent_custom_instructions"):
+            proj.update()
+
+
 class TestProjectUpdateBackwardsCompat:
     def test_multilingual_only_still_works(self, project):
         """Pre-decay callers (multilingual only) keep working unchanged."""