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"]